use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};
use everruns_capability::CapabilityRef as AgentCapabilityConfig;
use everruns_core::events::TokenUsage;
use everruns_core::mcp_server::{ScopedMcpServers, scoped_mcp_servers_is_empty};
use everruns_core::network_access::NetworkAccessList;
use everruns_core::principal::PrincipalSummary;
use everruns_core::session::{ExecutionSession, SessionExecutionState};
use everruns_provider::tool_types::ToolDefinition;
use everruns_provider::typed_id::{
AgentId, AgentIdentityId, AgentVersionId, HarnessId, ModelId, PrincipalId, SessionId,
SessionParticipantId, WorkspaceId,
};
#[cfg(feature = "openapi")]
use utoipa::ToSchema;
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
#[serde(rename_all = "lowercase")]
pub enum SessionStatus {
Started,
Active,
Idle,
WaitingForToolResults,
Paused,
}
impl SessionStatus {
pub fn execution_state(&self) -> SessionExecutionState {
match self {
SessionStatus::Started => SessionExecutionState::Started,
SessionStatus::Active => SessionExecutionState::Active,
SessionStatus::Idle => SessionExecutionState::Idle,
SessionStatus::WaitingForToolResults => SessionExecutionState::WaitingForToolResults,
SessionStatus::Paused => SessionExecutionState::Paused,
}
}
}
impl From<SessionExecutionState> for SessionStatus {
fn from(state: SessionExecutionState) -> Self {
match state {
SessionExecutionState::Started => SessionStatus::Started,
SessionExecutionState::Active => SessionStatus::Active,
SessionExecutionState::Idle => SessionStatus::Idle,
SessionExecutionState::WaitingForToolResults => SessionStatus::WaitingForToolResults,
SessionExecutionState::Paused => SessionStatus::Paused,
}
}
}
impl From<&SessionStatus> for SessionExecutionState {
fn from(status: &SessionStatus) -> Self {
status.execution_state()
}
}
impl std::fmt::Display for SessionStatus {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
SessionStatus::Started => write!(f, "started"),
SessionStatus::Active => write!(f, "active"),
SessionStatus::Idle => write!(f, "idle"),
SessionStatus::WaitingForToolResults => write!(f, "waiting_for_tool_results"),
SessionStatus::Paused => write!(f, "paused"),
}
}
}
impl From<&str> for SessionStatus {
fn from(s: &str) -> Self {
match s {
"active" => SessionStatus::Active,
"idle" => SessionStatus::Idle,
"waiting_for_tool_results" => SessionStatus::WaitingForToolResults,
"paused" => SessionStatus::Paused,
"running" => SessionStatus::Active,
"pending" | "completed" | "failed" => SessionStatus::Idle,
_ => SessionStatus::Started,
}
}
}
#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
#[serde(rename_all = "snake_case")]
pub enum SessionSource {
Chat,
Api,
Slack,
AgUi,
Fcp,
Schedule,
Webhook,
A2a,
Eval,
Subagent,
#[default]
Unknown,
}
impl SessionSource {
pub const ALL: &'static [SessionSource] = &[
SessionSource::Chat,
SessionSource::Api,
SessionSource::Slack,
SessionSource::AgUi,
SessionSource::Fcp,
SessionSource::Schedule,
SessionSource::Webhook,
SessionSource::A2a,
SessionSource::Eval,
SessionSource::Subagent,
SessionSource::Unknown,
];
pub fn as_str(self) -> &'static str {
match self {
SessionSource::Chat => "chat",
SessionSource::Api => "api",
SessionSource::Slack => "slack",
SessionSource::AgUi => "ag_ui",
SessionSource::Fcp => "fcp",
SessionSource::Schedule => "schedule",
SessionSource::Webhook => "webhook",
SessionSource::A2a => "a2a",
SessionSource::Eval => "eval",
SessionSource::Subagent => "subagent",
SessionSource::Unknown => "unknown",
}
}
pub fn parse(s: &str) -> Option<Self> {
Self::ALL.iter().copied().find(|v| v.as_str() == s)
}
pub fn is_client_declarable(self) -> bool {
matches!(self, SessionSource::Chat | SessionSource::Api)
}
}
impl std::fmt::Display for SessionSource {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.write_str(self.as_str())
}
}
impl From<&str> for SessionSource {
fn from(s: &str) -> Self {
Self::parse(s).unwrap_or(SessionSource::Unknown)
}
}
#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
#[serde(rename_all = "snake_case")]
pub enum SessionActivity {
Running,
Paused,
Failed,
Completed,
#[default]
Idle,
}
impl SessionActivity {
pub const ALL: &'static [SessionActivity] = &[
SessionActivity::Running,
SessionActivity::Paused,
SessionActivity::Failed,
SessionActivity::Completed,
SessionActivity::Idle,
];
pub fn as_str(self) -> &'static str {
match self {
SessionActivity::Running => "running",
SessionActivity::Paused => "paused",
SessionActivity::Failed => "failed",
SessionActivity::Completed => "completed",
SessionActivity::Idle => "idle",
}
}
pub fn parse(s: &str) -> Option<Self> {
Self::ALL.iter().copied().find(|v| v.as_str() == s)
}
pub fn derive(status: &SessionStatus, last_turn_status: Option<&str>) -> Self {
match status {
SessionStatus::Active | SessionStatus::WaitingForToolResults => {
SessionActivity::Running
}
SessionStatus::Paused => SessionActivity::Paused,
_ => match last_turn_status {
Some("failed") | Some("cancelled") => SessionActivity::Failed,
Some("completed") => SessionActivity::Completed,
_ => SessionActivity::Idle,
},
}
}
}
impl std::fmt::Display for SessionActivity {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.write_str(self.as_str())
}
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
#[serde(rename_all = "snake_case")]
pub enum SessionParticipantKind {
Agent,
User,
}
impl std::fmt::Display for SessionParticipantKind {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
SessionParticipantKind::Agent => write!(f, "agent"),
SessionParticipantKind::User => write!(f, "user"),
}
}
}
impl From<&str> for SessionParticipantKind {
fn from(s: &str) -> Self {
match s {
"agent" => SessionParticipantKind::Agent,
"user" => SessionParticipantKind::User,
_ => SessionParticipantKind::User,
}
}
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
#[serde(rename_all = "snake_case")]
pub enum SessionParticipantRole {
Host,
Member,
}
impl std::fmt::Display for SessionParticipantRole {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
SessionParticipantRole::Host => write!(f, "host"),
SessionParticipantRole::Member => write!(f, "member"),
}
}
}
impl From<&str> for SessionParticipantRole {
fn from(s: &str) -> Self {
match s {
"host" => SessionParticipantRole::Host,
"member" => SessionParticipantRole::Member,
_ => SessionParticipantRole::Member,
}
}
}
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
pub struct SessionParticipant {
#[cfg_attr(
feature = "openapi",
schema(
value_type = String,
example = "part_01933b5a00007000800000000000001"
)
)]
pub id: SessionParticipantId,
#[cfg_attr(
feature = "openapi",
schema(
value_type = String,
example = "session_01933b5a00007000800000000000001"
)
)]
pub session_id: SessionId,
pub kind: SessionParticipantKind,
#[serde(skip_serializing_if = "Option::is_none")]
#[cfg_attr(
feature = "openapi",
schema(
value_type = Option<String>,
example = "agent_01933b5a00007000800000000000001"
)
)]
pub agent_id: Option<AgentId>,
#[serde(skip_serializing_if = "Option::is_none")]
#[cfg_attr(
feature = "openapi",
schema(
value_type = Option<String>,
example = "agentver_01933b5a00007000800000000000001"
)
)]
pub agent_version_id: Option<AgentVersionId>,
#[cfg_attr(
feature = "openapi",
schema(
value_type = String,
example = "principal_01933b5a000070008000000000000001"
)
)]
pub principal_id: PrincipalId,
#[serde(skip_serializing_if = "Option::is_none")]
pub display_name: Option<String>,
pub role: SessionParticipantRole,
pub joined_at: DateTime<Utc>,
#[serde(skip_serializing_if = "Option::is_none")]
pub left_at: Option<DateTime<Utc>>,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
pub struct Session {
#[cfg_attr(feature = "openapi", schema(value_type = String, example = "session_01933b5a00007000800000000000001"))]
pub id: SessionId,
#[cfg_attr(feature = "openapi", schema(value_type = String, example = "org_00000000000000000000000000000001"))]
pub organization_id: String,
#[cfg_attr(feature = "openapi", schema(value_type = String, example = "wsp_01933b5a00007000800000000000001"))]
pub workspace_id: WorkspaceId,
#[cfg_attr(feature = "openapi", schema(value_type = String, example = "harness_01933b5a00007000800000000000001"))]
pub harness_id: HarnessId,
#[serde(skip_serializing_if = "Option::is_none")]
#[cfg_attr(feature = "openapi", schema(value_type = Option<String>, example = "agent_01933b5a00007000800000000000001"))]
pub agent_id: Option<AgentId>,
#[serde(skip_serializing_if = "Option::is_none")]
#[cfg_attr(feature = "openapi", schema(value_type = Option<String>, example = "agentver_01933b5a00007000800000000000001"))]
pub agent_version_id: Option<AgentVersionId>,
#[serde(skip_serializing_if = "Option::is_none")]
#[cfg_attr(feature = "openapi", schema(value_type = Option<String>, example = "identity_01933b5a00007000800000000000001"))]
pub agent_identity_id: Option<AgentIdentityId>,
#[cfg_attr(feature = "openapi", schema(value_type = String, example = "principal_01933b5a000070008000000000000001"))]
pub owner_principal_id: PrincipalId,
#[serde(skip_serializing_if = "Option::is_none")]
#[cfg_attr(
feature = "openapi",
schema(example = "550e8400-e29b-41d4-a716-446655440000")
)]
pub resolved_owner_user_id: Option<uuid::Uuid>,
#[serde(skip_serializing_if = "Option::is_none")]
pub owner: Option<PrincipalSummary>,
#[serde(skip_serializing_if = "Option::is_none")]
pub effective_owner: Option<PrincipalSummary>,
#[serde(skip_serializing_if = "Option::is_none")]
#[cfg_attr(feature = "openapi", schema(example = "Q3 marketing brief"))]
pub title: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
#[cfg_attr(
feature = "openapi",
schema(example = "Investigate the queue latency regression")
)]
pub goal: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
#[cfg_attr(feature = "openapi", schema(example = "en-US"))]
pub locale: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
#[cfg_attr(
feature = "openapi",
schema(example = "Help me draft the Q3 marketing plan")
)]
pub preview: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
#[cfg_attr(
feature = "openapi",
schema(example = "Here is a Q3 plan covering the three pillars we discussed...")
)]
pub output_preview: Option<String>,
#[serde(default)]
#[cfg_attr(feature = "openapi", schema(example = json!(["marketing", "q3", "draft"])))]
pub tags: Vec<String>,
#[serde(skip_serializing_if = "Option::is_none")]
#[cfg_attr(feature = "openapi", schema(value_type = Option<String>, example = "model_01933b5a00007000800000000000001"))]
pub model_id: Option<ModelId>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
#[cfg_attr(
feature = "openapi",
schema(value_type = Vec<crate::CapabilityRefSchema>)
)]
pub capabilities: Vec<AgentCapabilityConfig>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub tools: Vec<ToolDefinition>,
#[serde(
default,
rename = "mcpServers",
alias = "mcp_servers",
skip_serializing_if = "scoped_mcp_servers_is_empty"
)]
pub mcp_servers: ScopedMcpServers,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub system_prompt: Option<String>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub initial_files: Vec<everruns_core::session_file::InitialFile>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub hints: Option<std::collections::HashMap<String, serde_json::Value>>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub network_access: Option<NetworkAccessList>,
#[serde(default, skip_serializing_if = "Option::is_none")]
#[cfg_attr(feature = "openapi", schema(example = 50))]
pub max_iterations: Option<usize>,
#[serde(default, skip_serializing_if = "Option::is_none")]
#[cfg_attr(feature = "openapi", schema(example = true))]
pub parallel_tool_calls: Option<bool>,
pub status: SessionStatus,
#[serde(default)]
pub source: SessionSource,
#[serde(default)]
pub activity: SessionActivity,
#[cfg_attr(feature = "openapi", schema(example = "2026-05-25T10:00:00Z"))]
pub created_at: DateTime<Utc>,
#[cfg_attr(feature = "openapi", schema(example = "2026-05-25T10:14:32Z"))]
pub updated_at: DateTime<Utc>,
#[serde(skip_serializing_if = "Option::is_none")]
#[cfg_attr(feature = "openapi", schema(example = "2026-05-25T10:00:01Z"))]
pub started_at: Option<DateTime<Utc>>,
#[serde(skip_serializing_if = "Option::is_none")]
#[cfg_attr(feature = "openapi", schema(example = "2026-05-25T10:14:32Z"))]
pub finished_at: Option<DateTime<Utc>>,
#[serde(skip_serializing_if = "Option::is_none")]
pub usage: Option<TokenUsage>,
#[serde(skip_serializing_if = "Option::is_none")]
#[cfg_attr(feature = "openapi", schema(example = false))]
pub is_pinned: Option<bool>,
#[serde(skip_serializing_if = "Option::is_none")]
#[cfg_attr(feature = "openapi", schema(example = 2))]
pub active_schedule_count: Option<u32>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
#[cfg_attr(feature = "openapi", schema(example = json!(["file_system", "secrets"])))]
pub features: Vec<String>,
#[serde(skip_serializing_if = "Option::is_none")]
#[cfg_attr(feature = "openapi", schema(value_type = Option<String>))]
pub parent_session_id: Option<SessionId>,
#[serde(default, skip_serializing_if = "Option::is_none")]
#[cfg_attr(feature = "openapi", schema(value_type = Option<String>))]
pub forked_from_session_id: Option<SessionId>,
#[serde(default, skip_serializing_if = "Option::is_none")]
#[cfg_attr(feature = "openapi", schema(example = 42))]
pub forked_from_sequence: Option<i32>,
#[serde(skip_serializing_if = "Option::is_none")]
#[cfg_attr(feature = "openapi", schema(example = "blueprint_research_pack"))]
pub blueprint_id: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
#[cfg_attr(feature = "openapi", schema(value_type = Option<Object>))]
pub blueprint_config: Option<serde_json::Value>,
}
impl Session {
pub fn from_execution_session(
execution: ExecutionSession,
owner_principal_id: PrincipalId,
) -> Self {
let status = SessionStatus::from(execution.status);
let activity = SessionActivity::derive(&status, None);
let now = Utc::now();
Self {
id: execution.id,
organization_id: execution.organization_id,
workspace_id: execution.workspace_id,
harness_id: execution.harness_id,
agent_id: execution.agent_id,
agent_version_id: None,
agent_identity_id: None,
owner_principal_id,
resolved_owner_user_id: None,
owner: None,
effective_owner: None,
title: execution.title,
goal: execution.goal,
locale: execution.locale,
preview: None,
output_preview: None,
tags: execution.tags,
model_id: execution.model_id,
capabilities: execution.capabilities,
tools: execution.tools,
mcp_servers: execution.mcp_servers,
system_prompt: execution.system_prompt,
initial_files: execution.initial_files,
hints: execution.hints,
network_access: execution.network_access,
max_iterations: execution.max_iterations,
parallel_tool_calls: execution.parallel_tool_calls,
status,
source: SessionSource::Unknown,
activity,
created_at: now,
updated_at: now,
started_at: None,
finished_at: None,
usage: execution.usage,
is_pinned: None,
active_schedule_count: None,
features: Vec::new(),
parent_session_id: execution.parent_session_id,
forked_from_session_id: execution.forked_from_session_id,
forked_from_sequence: None,
blueprint_id: execution.blueprint_id,
blueprint_config: execution.blueprint_config,
}
}
pub fn execution_session(&self) -> ExecutionSession {
ExecutionSession {
id: self.id,
organization_id: self.organization_id.clone(),
workspace_id: self.workspace_id,
harness_id: self.harness_id,
agent_id: self.agent_id,
title: self.title.clone(),
goal: self.goal.clone(),
locale: self.locale.clone(),
tags: self.tags.clone(),
model_id: self.model_id,
capabilities: self.capabilities.clone(),
tools: self.tools.clone(),
mcp_servers: self.mcp_servers.clone(),
system_prompt: self.system_prompt.clone(),
initial_files: self.initial_files.clone(),
hints: self.hints.clone(),
network_access: self.network_access.clone(),
max_iterations: self.max_iterations,
parallel_tool_calls: self.parallel_tool_calls,
status: self.status.execution_state(),
usage: self.usage.clone(),
parent_session_id: self.parent_session_id,
forked_from_session_id: self.forked_from_session_id,
blueprint_id: self.blueprint_id.clone(),
blueprint_config: self.blueprint_config.clone(),
}
}
}
impl From<&Session> for everruns_core::AgentConfigOverlay {
fn from(session: &Session) -> Self {
(&session.execution_session()).into()
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn activity_derivation_truth_table() {
use SessionActivity as A;
use SessionStatus as S;
let cases: &[(SessionStatus, Option<&str>, SessionActivity)] = &[
(S::Active, None, A::Running),
(S::Active, Some("failed"), A::Running),
(S::WaitingForToolResults, Some("completed"), A::Running),
(S::Paused, Some("failed"), A::Paused),
(S::Idle, Some("completed"), A::Completed),
(S::Idle, Some("failed"), A::Failed),
(S::Idle, Some("cancelled"), A::Failed),
(S::Started, Some("completed"), A::Completed),
(S::Started, None, A::Idle),
(S::Idle, None, A::Idle),
(S::Idle, Some("weird"), A::Idle),
];
for (status, last_turn, expected) in cases {
assert_eq!(
SessionActivity::derive(status, *last_turn),
*expected,
"status={status} last_turn={last_turn:?}"
);
}
}
#[test]
fn session_source_round_trips_through_its_wire_string() {
for source in SessionSource::ALL {
assert_eq!(SessionSource::parse(source.as_str()), Some(*source));
}
assert_eq!(SessionSource::from("not_a_source"), SessionSource::Unknown);
}
#[test]
fn only_chat_and_api_are_client_declarable() {
let declarable: Vec<_> = SessionSource::ALL
.iter()
.filter(|s| s.is_client_declarable())
.copied()
.collect();
assert_eq!(declarable, vec![SessionSource::Chat, SessionSource::Api]);
}
#[test]
fn session_activity_round_trips_through_its_wire_string() {
for activity in SessionActivity::ALL {
assert_eq!(SessionActivity::parse(activity.as_str()), Some(*activity));
}
assert_eq!(SessionActivity::parse("nope"), None);
}
#[test]
fn lifted_execution_view_round_trips_through_the_stored_record() {
let execution = ExecutionSession {
agent_id: Some(everruns_provider::typed_id::AgentId::from_seed(7)),
title: Some("Lifted".to_string()),
tags: vec!["a".to_string()],
status: SessionExecutionState::Idle,
..ExecutionSession::with_own_workspace(SessionId::new(), HarnessId::new())
};
let lifted = Session::from_execution_session(execution.clone(), PrincipalId::from_seed(1));
assert_eq!(lifted.source, SessionSource::Unknown);
assert_eq!(lifted.activity, SessionActivity::Idle);
assert_eq!(lifted.status, SessionStatus::Idle);
let round_tripped = lifted.execution_session();
assert_eq!(
serde_json::to_value(&round_tripped).unwrap(),
serde_json::to_value(&execution).unwrap()
);
}
#[test]
fn stored_status_round_trips_through_the_neutral_execution_state() {
for status in [
SessionStatus::Started,
SessionStatus::Active,
SessionStatus::Idle,
SessionStatus::WaitingForToolResults,
SessionStatus::Paused,
] {
let state = status.execution_state();
assert_eq!(SessionStatus::from(state), status);
assert_eq!(status.to_string(), state.to_string());
}
}
}