[FEATURE]: A runtime that owns sessions and their runs #780

// crates/aura/src/run_context.rs — as implemented on PR #719's head, abbreviated.
// "One run — what its own work needs to correlate, where its events go, and
// the state an agent's tools keep for it."
pub struct RunContext {
    id: Arc<str>,                               // becomes RunId (#778) in PR #730's rebase
    tool_calls: Mutex<VecDeque<ToolCallId>>,
    events: mpsc::Sender<AgentEvent>,
    cancel: CancellationToken,
    scratchpad_budget: Option<ContextBudget>,
    turn_nudge: Option<Arc<TurnNudgeState>>,
    skill_recorder: Option<Arc<SkillInvocationRecorder>>,   // e54d2bc6
    // proposed by #781, written by the runtime on attach, detach, and run start:
    present: Arc<AtomicBool>,                   // some observer is present — read by the HITL gate (#786); shared with child runs
    claimed: Arc<AtomicBool>,                   // a claimant exists — read by liveness (#784); shared with child runs
}
impl RunContext {
    /// A run carrying the state a prepared agent's tools keep for it, and the
    /// receiver its observer reads. What `PreparedAgent::begin_run` calls.
    pub fn channel_for_agent(id, cancel, scratchpad_budget, turn_nudge, skill_recorder)
        -> (Arc<Self>, mpsc::Receiver<AgentEvent>);
    /// A run within `parent` for one agent of it — an orchestration worker or
    /// coordinator: same id, observer, and cancellation; tool state of its own.
    pub fn child(parent: &Arc<Self>, scratchpad_budget, turn_nudge, skill_recorder) -> Arc<Self>;
}

/// A run in progress on a prepared agent. The `Agent` holds one; the
/// `PreparedAgent` holds a `Weak` to it and refuses `begin_run` while it lives.
pub struct RunLease { run: Arc<RunContext> }

/// The slot tools resolve the current run through. One per prepared agent.
pub struct BoundRun(Mutex<Option<Arc<RunContext>>>);

// proposed — aura::runtime

// struct name? See discussion question 1 @ https://github.com/mezmo/aura/discussions/743#discussioncomment-18800261
pub struct Runtime {                            // name: discussion 743 question 1
    configs: Arc<Vec<aura_config::Config>>,     // what prepare_agent builds from
    sessions: RwLock<HashMap<SessionId, Arc<SessionRecord>>>,  // sessions this process holds
    runs: RwLock<HashMap<RunId, SessionId>>,    // index: which session a run belongs to
    run_store: Arc<dyn RunStore>,               // facts and the session index; memory today
    journals: Arc<dyn JournalStore>,            // event storage; memory today
    retention: Duration,                        // how long an ended run stays live; the stores bound themselves
}

// aura::session_store — beside ApprovalStore, TaskStore, SkillInvocationStore, EventBus
#[async_trait]
pub trait RunStore: Send + Sync {
    async fn put(&self, facts: &RunFacts) -> Result<(), StoreError>;
    async fn get(&self, run: &RunId) -> Result<Option<RunFacts>, StoreError>;
    async fn list(&self, filter: &RunFilter) -> Result<Vec<RunFacts>, StoreError>;
    /// The terminal write: the run's last journal event and its final facts,
    /// atomic where the backend can make them so.
    async fn finish(&self, terminal: &SessionEvent, facts: &RunFacts) -> Result<(), StoreError>;
}
// No `retire`: the memory impl bounds itself by a cap, a durable impl by TTL.

pub struct RunFilter { pub session: Option<SessionId>, pub status: Option<RunStatus>, pub pending_approval: Option<bool>, pub limit: usize, pub after: Option<RunId> }

/// Live process state for one session. Crate-private and never `Serialize`.
pub(crate) struct SessionRecord {
    id: SessionId,
    agent_id: String,                           // AgentInfo::id
    agent: Mutex<AgentSlot>,                    // #787 keeps this Ready across runs
    journal: Arc<SessionJournal>,               // #779
    observers: RwLock<ObserverSet>,             // #781 — instance-local, never persisted
    run: RwLock<Option<Arc<RunRecord>>>,        // the live run; at most one
    last_run: RwLock<Option<RunId>>,
}
pub(crate) enum AgentSlot { Absent, Preparing, Ready(Arc<PreparedAgent>) }

/// Live process state for one run. Crate-private and never `Serialize`: it
/// holds a task, locks, atomics, and the run's context. What crosses to a
/// caller is `facts`.
pub(crate) struct RunRecord {
    id: RunId,
    context: Arc<RunContext>,
    task: JoinHandle<()>,                       // drives the AgentRun to completion and appends its events
    usage: UsageState,                          // live counters from the AgentRun
    facts: RwLock<RunFacts>,
}

/// The durable half of a run: everything about it that outlives the process
/// and is safe to serialize. `RunSummary` (#785) is this plus observer counts.
#[derive(Serialize, Deserialize)]
pub struct RunFacts {
    pub run_id: RunId,
    pub session_id: SessionId,
    pub agent: String,                          // AgentInfo::id
    pub status: RunStatus,
    pub liveness: Liveness,                     // aura_events::run, #784
    pub started_at: Timestamp,
    pub ended_at: Option<Timestamp>,
    pub usage: TokenUsage,                      // the live counters while running; final at the terminal write
    pub first_seq: Option<SequenceNumber>,      // the run's `Started` in the session stream; the attach cursor
    pub latest_seq: Option<SequenceNumber>,
    pub pending_approvals: Vec<DecisionId>,     // ids only; the decisions live in ApprovalStore
    pub checkpoint: Option<CheckpointRef>,      // a store key, never a local path
    pub continues: Option<RunId>,               // the run this one resumed or followed
}

#[derive(Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum RunStatus { Preparing, Running, Finished, Failed, Cancelled, Parked }

/// The session's outward state — constructed, never stored, never an event.
/// What #785's session summary reports.
#[derive(Serialize)]
#[serde(tag = "state", rename_all = "snake_case")]
pub enum AgentState {
    Preparing,                                  // agent slot is Preparing: MCP discovery, later the session claim
    Running,                                    // a live run with nothing pending
    Blocked { on: BlockReason },                // a live run waiting on something outside the model
    Parked,                                     // last run parked; nothing in memory; resumable
    Done,                                       // no live run; the agent comes back with history on the next start
}
#[derive(Serialize)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum BlockReason {
    Approval { decisions: Vec<DecisionId> },    // pending_approvals non-empty, not yet parked
    ProviderRetry { attempt: u32 },             // the run's last Retrying event (#778) with no turn since
}

/// What a seam hands the runtime. No agent in it: the runtime prepares one.
pub struct StartRun {
    pub agent: Option<String>,                  // AgentInfo::id; the default agent when absent
    pub req_headers: Option<HashMap<String, String>>, // forwarded per `headers_from_request`
    pub client_tools: Option<Vec<ClientTool>>,
    pub additional_tools: Vec<Box<dyn ToolDyn>>,
    pub session: Option<SessionId>,             // a new session when absent
    pub continues: Option<RunId>,               // the run this one follows, if any
    pub prompt: String,
    pub history: Vec<Message>,
    pub options: RunOptions,                    // PR #710: timeout, parent token
    pub liveness: Liveness,                     // #784; the seam supplies its config default
}

pub enum StartError {
    NoSuchAgent(String),
    RunInProgress(RunId),                       // the session's live run; attach to it
    PolicyUnsupported { policy: LivenessPolicy, agent: String },   // e.g. Park without checkpoint support
    Store(StoreError),
}

impl Runtime {
    /// Mints the RunId, writes initial facts (`Preparing`), spawns the run's
    /// task, and returns at once. `Started` follows on the session's journal
    /// once the agent is ready and the run begun.
    pub async fn start(&self, req: StartRun) -> Result<RunId, StartError>;
    /// Facts with usage snapshotted from the live counters while running.
    pub fn facts(&self, run: &RunId) -> Option<RunFacts>;
    /// The session's outward state, constructed from the agent slot, the live
    /// run's facts, and its pending approvals and retry signal.
    pub fn session_state(&self, session: &SessionId) -> Option<AgentState>;
    pub fn observer_counts(&self, session: &SessionId) -> Option<ObserverCounts>;   // #781
    pub async fn list(&self, filter: &RunFilter) -> Result<Vec<RunFacts>, StoreError>;
    pub async fn cancel(&self, run: &RunId, reason: RunCancelReason, message: Option<String>) -> bool;
    /// Shutdown: cancel every live run with `Shutdown`, wait `grace`, abort the rest.
    pub async fn drain(&self, grace: Duration);
}