rlmesh-runtime 0.1.0-rc.3

//! Event payloads the driver hands to each [`RuntimeHooks`](super::RuntimeHooks)
//! callback. Each carries its route/session identity inline, since one hooks
//! instance serves every concurrent route.

use std::sync::Arc;

use prost::bytes::Bytes;
use rlmesh_proto::spaces::v1::MetaMap;
use rlmesh_proto::spaces::v1::SpaceSpec;

#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct RuntimeEnvContext {
    pub env_id: String,
    pub env_component_id: String,
    pub model_component_id: String,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct EnvConnectedEvent {
    pub session_id: String,
    pub route: RuntimeEnvContext,
    pub env_id: String,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ModelConnectedEvent {
    pub session_id: String,
    pub route: RuntimeEnvContext,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SessionStartedEvent {
    pub session_id: String,
    pub route: RuntimeEnvContext,
    pub env_id: String,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SessionEndedEvent {
    pub session_id: String,
    pub route: RuntimeEnvContext,
    pub reason: String,
    pub total_steps: i64,
    pub total_episodes: i64,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SessionFailedEvent {
    pub session_id: String,
    pub route: RuntimeEnvContext,
    pub reason: String,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct LogEvent {
    pub session_id: String,
    pub route: RuntimeEnvContext,
    pub level: LogLevel,
    pub message: String,
    pub source: Option<String>,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum LogLevel {
    Debug,
    Info,
    Warn,
    Error,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct EpisodeStartedEvent {
    pub session_id: String,
    pub route: RuntimeEnvContext,
    pub episode_id: String,
    pub episode_record_id: String,
    pub episode_index: i64,
    pub env_index: i32,
    pub started_from_auto_reset: bool,
}

#[derive(Debug, Clone, PartialEq)]
pub struct EpisodeCompletedEvent {
    pub session_id: String,
    pub route: RuntimeEnvContext,
    pub episode_id: String,
    pub episode_record_id: String,
    pub episode_index: i64,
    pub env_index: i32,
    pub step_count: i64,
    pub cumulative_reward: f64,
    pub terminated: bool,
    pub truncated: bool,
    pub duration_ms: i64,
    pub final_info: Option<MetaMap>,
}

#[derive(Debug, Clone, PartialEq)]
pub struct ActionReceivedEvent {
    pub session_id: String,
    pub route: RuntimeEnvContext,
    pub episode_id: String,
    pub episode_record_id: String,
    pub episode_ids: Vec<String>,
    pub episode_record_ids: Vec<String>,
    pub step: i64,
    pub env_index: i32,
    /// Shared so the per-step, per-hook event fan-out clones an `Arc` pointer
    /// rather than deep-copying the action space spec on every step.
    pub action_space: Arc<SpaceSpec>,
    /// Opaque per-leaf wire bytes; the relay is content-blind (§13).
    ///
    /// To persist as a single artifact, use `rlmesh-grpc`'s
    /// `wire::leaves_to_blob` — plain concatenation loses the leaf
    /// boundaries, which cannot be recovered for variable-length leaves.
    pub action: Option<Vec<Bytes>>,
}

#[derive(Debug, Clone, PartialEq)]
pub struct StepCompletedEvent {
    pub session_id: String,
    pub route: RuntimeEnvContext,
    pub episode_id: String,
    pub episode_record_id: String,
    pub step: i64,
    pub env_index: i32,
    pub rewards: Vec<f64>,
}

#[derive(Debug, Clone, PartialEq)]
pub struct ObservationEmittedEvent {
    pub session_id: String,
    pub route: RuntimeEnvContext,
    pub episode_id: String,
    pub episode_record_id: String,
    pub episode_ids: Vec<String>,
    pub episode_record_ids: Vec<String>,
    pub step: i64,
    pub env_index: i32,
    pub is_reset: bool,
    pub num_envs: u32,
    /// Shared so the per-step, per-hook event fan-out clones an `Arc` pointer
    /// rather than deep-copying the observation space spec on every step.
    pub observation_space: Arc<SpaceSpec>,
    /// Opaque per-leaf wire bytes; the relay is content-blind (§13).
    ///
    /// To persist as a single artifact, use `rlmesh-grpc`'s
    /// `wire::leaves_to_blob` — plain concatenation loses the leaf
    /// boundaries, which cannot be recovered for variable-length leaves.
    pub observation: Option<Vec<Bytes>>,
}

/// A live telemetry snapshot tagged with the route/session it belongs to.
///
/// The managed runner shares one `RuntimeHooks` across concurrent routes, so —
/// like every other event — the snapshot carries identity inline. Identity
/// lives on the event, not on the `Snapshot` itself, which stays a pure metrics
/// payload (it is also the durable `RuntimeReport.telemetry`). Use
/// `snapshot.horizon` to tell a window tick from the cumulative session.
#[derive(Debug, Clone, PartialEq)]
pub struct TelemetrySnapshotEvent {
    pub session_id: String,
    pub route: RuntimeEnvContext,
    pub snapshot: crate::telemetry::Snapshot,
}