honcho-ai 0.2.1

//! Session-related types for the Honcho API.

use std::collections::HashMap;

use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};

pub use super::common::{
    DreamConfiguration, PeerCardConfiguration, ReasoningConfiguration, SummaryConfiguration,
};
pub use super::dream::SessionQueueStatus;

/// A conversation session containing messages between peers.
#[non_exhaustive]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct SessionResponse {
    /// Unique session identifier.
    pub id: String,
    /// Whether the session is currently active.
    pub is_active: bool,
    /// The workspace this session belongs to.
    pub workspace_id: String,
    /// Arbitrary key-value metadata attached to the session.
    #[serde(default, skip_serializing_if = "HashMap::is_empty")]
    pub metadata: HashMap<String, serde_json::Value>,
    /// Session-level configuration overrides.
    #[serde(default)]
    pub configuration: SessionConfiguration,
    /// When the session was created.
    pub created_at: DateTime<Utc>,
}

/// Request body for creating a new session.
#[non_exhaustive]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, bon::Builder)]
#[builder(on(String, into))]
#[builder(finish_fn = build)]
pub struct SessionCreate {
    /// Unique session identifier (alphanumeric, hyphens, underscores).
    pub id: String,
    /// Optional metadata to attach.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub metadata: Option<HashMap<String, serde_json::Value>>,
    /// Peer configurations keyed by peer ID.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub peers: Option<HashMap<String, SessionPeerConfig>>,
    /// Optional session-level configuration.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub configuration: Option<SessionConfiguration>,
}

impl SessionCreate {
    /// Validate session ID constraints.
    pub fn validate(&self) -> crate::error::Result<()> {
        if self.id.is_empty() {
            return Err(crate::error::HonchoError::Validation(
                "session id must not be empty".into(),
            ));
        }
        if !self
            .id
            .chars()
            .all(|c| c.is_ascii_alphanumeric() || c == '-' || c == '_')
        {
            return Err(crate::error::HonchoError::Validation(
                "session id must contain only [a-zA-Z0-9_-]".into(),
            ));
        }
        Ok(())
    }
}

/// Request body for updating a session.
#[non_exhaustive]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, bon::Builder)]
#[builder(on(String, into))]
#[builder(finish_fn = build)]
pub struct SessionUpdate {
    /// Updated metadata (replaces existing).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub metadata: Option<HashMap<String, serde_json::Value>>,
    /// Updated session configuration (merges with existing).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub configuration: Option<SessionConfiguration>,
}

/// Query parameters for listing/getting sessions.
#[non_exhaustive]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, bon::Builder)]
#[builder(on(String, into))]
#[builder(finish_fn = build)]
pub struct SessionGet {
    /// Filter criteria for sessions.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub filters: Option<HashMap<String, serde_json::Value>>,
}

/// Request body for setting session metadata.
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct SessionMetadataSet {
    /// Metadata to set.
    pub metadata: HashMap<String, serde_json::Value>,
}

/// Request body for setting session configuration.
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct SessionConfigurationSet {
    /// Configuration to set.
    pub configuration: HashMap<String, serde_json::Value>,
}

/// Session-level configuration overrides.
///
/// All fields are optional. Session-level configuration overrides
/// workspace-level configuration, which overrides global configuration.
#[non_exhaustive]
#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq)]
pub struct SessionConfiguration {
    /// Configuration for reasoning functionality.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub reasoning: Option<ReasoningConfiguration>,
    /// Configuration for peer card functionality.
    ///
    /// If reasoning is disabled, peer cards will also be disabled
    /// and these settings will be ignored.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub peer_card: Option<PeerCardConfiguration>,
    /// Configuration for summary functionality.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub summary: Option<SummaryConfiguration>,
    /// Configuration for dream functionality.
    ///
    /// If reasoning is disabled, dreams will also be disabled
    /// and these settings will be ignored.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub dream: Option<DreamConfiguration>,
}

/// Per-peer observation settings within a session.
#[non_exhaustive]
#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq)]
pub struct SessionPeerConfig {
    /// Whether Honcho will use reasoning to form a representation of this peer.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub observe_me: Option<bool>,
    /// Whether this peer should form session-level representations of other peers.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub observe_others: Option<bool>,
}

/// Options for `Session::context_with_options`.
#[non_exhaustive]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, bon::Builder)]
#[builder(on(String, into))]
#[builder(finish_fn = build)]
pub struct SessionContextOptions {
    /// Whether to include the session summary.
    #[serde(default = "default_true")]
    #[builder(default = true)]
    pub summary: bool,
    /// Whether to limit representation context to this session only.
    #[serde(default)]
    #[builder(default)]
    pub limit_to_session: bool,
    /// Maximum number of tokens to include in the context.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub tokens: Option<u32>,
    /// A peer ID to get context for.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub peer_target: Option<String>,
    /// A peer ID to get context from the perspective of.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub peer_perspective: Option<String>,
    /// A query string used to fetch semantically relevant conclusions.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub search_query: Option<String>,
    /// Number of semantically relevant facts to return when searching.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub search_top_k: Option<u32>,
    /// Maximum semantic distance for search results (0.0–1.0).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub search_max_distance: Option<f64>,
    /// Whether to include the most frequent conclusions.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub include_most_frequent: Option<bool>,
    /// Maximum number of conclusions to include.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub max_conclusions: Option<u32>,
}

pub(crate) const SEARCH_TOP_K_MIN: u32 = 1;
pub(crate) const SEARCH_TOP_K_MAX: u32 = 100;
pub(crate) const SEARCH_MAX_DISTANCE_MIN: f64 = 0.0;
pub(crate) const SEARCH_MAX_DISTANCE_MAX: f64 = 1.0;
pub(crate) const MAX_CONCLUSIONS_MIN: u32 = 1;
pub(crate) const MAX_CONCLUSIONS_MAX: u32 = 100;

/// Validate optional search/conclusion parameters.
///
/// Checks that `search_top_k` is in 1–100, `search_max_distance` is in 0.0–1.0,
/// and `max_conclusions` is in 1–100. Returns `Err(HonchoError::Validation)` on
/// any out-of-range value.
pub(crate) fn validate_search_params(
    search_top_k: Option<u32>,
    search_max_distance: Option<f64>,
    max_conclusions: Option<u32>,
) -> crate::error::Result<()> {
    if let Some(k) = search_top_k
        && !(SEARCH_TOP_K_MIN..=SEARCH_TOP_K_MAX).contains(&k)
    {
        return Err(crate::error::HonchoError::Validation(format!(
            "search_top_k must be between {SEARCH_TOP_K_MIN} and {SEARCH_TOP_K_MAX}, got {k}"
        )));
    }
    if let Some(d) = search_max_distance
        && !(SEARCH_MAX_DISTANCE_MIN..=SEARCH_MAX_DISTANCE_MAX).contains(&d)
    {
        return Err(crate::error::HonchoError::Validation(format!(
            "search_max_distance must be between {SEARCH_MAX_DISTANCE_MIN} and {SEARCH_MAX_DISTANCE_MAX}, got {d}"
        )));
    }
    if let Some(c) = max_conclusions
        && !(MAX_CONCLUSIONS_MIN..=MAX_CONCLUSIONS_MAX).contains(&c)
    {
        return Err(crate::error::HonchoError::Validation(format!(
            "max_conclusions must be between {MAX_CONCLUSIONS_MIN} and {MAX_CONCLUSIONS_MAX}, got {c}"
        )));
    }
    Ok(())
}

impl SessionContextOptions {
    /// Validate cross-field constraints.
    ///
    /// Enforces that `peer_perspective` and `search_query` each require
    /// `peer_target`, that range-bounded numeric fields are in range, and that
    /// `tokens` (when set) is non-zero.
    ///
    /// Note: `search_top_k` and `search_max_distance` only take effect together
    /// with `search_query`, and `max_conclusions` together with
    /// `include_most_frequent`. They are intentionally NOT hard-rejected when
    /// their companion is absent: the server ignores them in that case, and
    /// rejecting locally would couple this client to server-side semantics that
    /// may relax over time. Setting them without their companion is therefore a
    /// no-op rather than an error.
    pub fn validate(&self) -> crate::error::Result<()> {
        if self.peer_perspective.is_some() && self.peer_target.is_none() {
            return Err(crate::error::HonchoError::Validation(
                "peer_perspective requires peer_target to be set".into(),
            ));
        }
        if self.search_query.is_some() && self.peer_target.is_none() {
            return Err(crate::error::HonchoError::Validation(
                "search_query requires peer_target to be set".into(),
            ));
        }
        validate_search_params(
            self.search_top_k,
            self.search_max_distance,
            self.max_conclusions,
        )?;
        if let Some(t) = self.tokens
            && t == 0
        {
            return Err(crate::error::HonchoError::Validation(
                "tokens must be greater than 0".into(),
            ));
        }
        Ok(())
    }

    /// Render the options as query-string key/value pairs.
    ///
    /// Returns borrowed `&'static str` keys and `Cow` values so that string
    /// options (`peer_target`, `peer_perspective`, `search_query`) and boolean
    /// literals are borrowed without allocation; only numeric values that must
    /// be formatted are owned. This avoids the clone-then-discard round-trip a
    /// `Vec<(&str, String)>` would force on the caller.
    pub(crate) fn to_query_params(&self) -> Vec<(&'static str, std::borrow::Cow<'_, str>)> {
        use std::borrow::Cow;

        let mut params: Vec<(&'static str, Cow<'_, str>)> = vec![
            (
                "summary",
                Cow::Borrowed(if self.summary { "true" } else { "false" }),
            ),
            (
                "limit_to_session",
                Cow::Borrowed(if self.limit_to_session {
                    "true"
                } else {
                    "false"
                }),
            ),
        ];
        if let Some(v) = self.tokens {
            params.push(("tokens", Cow::Owned(v.to_string())));
        }
        if let Some(ref v) = self.peer_target {
            params.push(("peer_target", Cow::Borrowed(v.as_str())));
        }
        if let Some(ref v) = self.peer_perspective {
            params.push(("peer_perspective", Cow::Borrowed(v.as_str())));
        }
        if let Some(ref v) = self.search_query {
            params.push(("search_query", Cow::Borrowed(v.as_str())));
        }
        if let Some(v) = self.search_top_k {
            params.push(("search_top_k", Cow::Owned(v.to_string())));
        }
        if let Some(v) = self.search_max_distance {
            params.push(("search_max_distance", Cow::Owned(v.to_string())));
        }
        if let Some(v) = self.include_most_frequent {
            params.push((
                "include_most_frequent",
                Cow::Borrowed(if v { "true" } else { "false" }),
            ));
        }
        if let Some(v) = self.max_conclusions {
            params.push(("max_conclusions", Cow::Owned(v.to_string())));
        }
        params
    }
}

fn default_true() -> bool {
    true
}

/// Escape a value before interpolating it into a pseudo-XML `<tag>…</tag>`
/// wrapper.
///
/// Security control: context values (summaries, peer representations, peer
/// cards) are influenced by session content and are therefore attacker-
/// controllable. Without escaping, a value containing e.g. `</summary>` would
/// break out of its tag framing, corrupting the message structure and enabling
/// prompt injection. We HTML-escape `&`, `<`, and `>` (ampersand first, so the
/// substitution stays unambiguous and reversible), which makes it impossible
/// for a value to forge or close a tag.
fn escape_tag_value(value: &str) -> std::borrow::Cow<'_, str> {
    if value.contains(['&', '<', '>']) {
        std::borrow::Cow::Owned(
            value
                .replace('&', "&amp;")
                .replace('<', "&lt;")
                .replace('>', "&gt;"),
        )
    } else {
        std::borrow::Cow::Borrowed(value)
    }
}

/// Context returned when requesting session state.
#[non_exhaustive]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct SessionContext {
    /// Session identifier.
    pub id: String,
    /// Messages in the session.
    pub messages: Vec<super::message::MessageResponse>,
    /// The summary if available.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub summary: Option<Summary>,
    /// Curated subset of a peer representation, if requested from a specific perspective.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub peer_representation: Option<String>,
    /// The peer card, if requested from a specific perspective.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub peer_card: Option<Vec<String>>,
}

/// Summaries for a session (short and/or long).
#[non_exhaustive]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct SessionSummaries {
    /// Session identifier.
    pub id: String,
    /// The short summary if available.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub short_summary: Option<Summary>,
    /// The long summary if available.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub long_summary: Option<Summary>,
}

/// The type of session summary.
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum SummaryType {
    /// Short summary generated more frequently.
    Short,
    /// Long summary generated less frequently.
    Long,
    /// A summary type not recognized by this client version.
    ///
    /// Acts as a forward-compatibility catch-all: a new summary type added
    /// server-side deserializes here instead of failing the whole
    /// `SessionContext` deserialization.
    #[serde(other)]
    Unknown,
}

/// A session summary covering messages up to a point.
#[non_exhaustive]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct Summary {
    /// The summary text.
    pub content: String,
    /// The public ID of the message this summary covers up to.
    pub message_id: String,
    /// The type of summary.
    pub summary_type: SummaryType,
    /// When the summary was created.
    pub created_at: DateTime<Utc>,
    /// Number of tokens in the summary text.
    pub token_count: u32,
}

/// Options for listing sessions with filters and pagination.
#[non_exhaustive]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, bon::Builder)]
#[builder(on(String, into))]
#[builder(finish_fn = build)]
pub struct SessionListOptions {
    /// Filter criteria for sessions.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub filters: Option<HashMap<String, serde_json::Value>>,
    /// Page number (1-based).
    #[serde(default = "default_page")]
    #[builder(default = default_page())]
    pub page: u64,
    /// Page size. Must be in `1..=100`.
    #[serde(default = "default_size")]
    #[builder(default = default_size())]
    pub size: u64,
    /// Reverse order.
    #[serde(default)]
    #[builder(default)]
    pub reverse: bool,
}

fn default_page() -> u64 {
    1
}

fn default_size() -> u64 {
    50
}

/// A paginated list of sessions.
pub type SessionPage = super::pagination::Page<SessionResponse>;

/// Resolves an assistant name from various reference types.
///
/// Implemented for `&str`, `String`, and `&Peer` so that
/// [`SessionContext::to_openai`] and [`SessionContext::to_anthropic`]
/// can accept any of these without extra boilerplate.
// NOTE: trait name retained for public-API stability; any rename is a
// separate breaking change deferred to a future major release.
pub trait IntoAssistantRef {
    /// Return the string name/id to use as the assistant.
    fn as_assistant_name(&self) -> &str;
}

impl IntoAssistantRef for &str {
    fn as_assistant_name(&self) -> &str {
        self
    }
}

impl IntoAssistantRef for String {
    fn as_assistant_name(&self) -> &str {
        self.as_str()
    }
}

impl IntoAssistantRef for &crate::Peer {
    fn as_assistant_name(&self) -> &str {
        self.id()
    }
}

impl SessionContext {
    /// Format a peer card into a single displayable string.
    ///
    /// Each item is single-quoted with backslash escaping. The backslash is
    /// escaped FIRST, then the single quote, so the output is unambiguous and
    /// parseable: a trailing `\` cannot consume the closing quote (e.g. `foo\`
    /// becomes `'foo\\'`, not `'foo\'`).
    fn format_peer_card(card: &[String]) -> String {
        let items: Vec<String> = card
            .iter()
            .map(|s| format!("'{}'", s.replace('\\', "\\\\").replace('\'', "\\'")))
            .collect();
        format!("[{}]", items.join(", "))
    }

    /// Build context system messages shared across provider formats.
    ///
    /// Returns `(content_tag, content_value)` pairs for `peer_representation`,
    /// `peer_card`, and `summary`, in that order.
    fn build_context_messages(&self) -> Vec<(&'static str, std::borrow::Cow<'_, str>)> {
        let mut msgs = Vec::new();
        if let Some(ref rep) = self.peer_representation {
            msgs.push((
                "peer_representation",
                std::borrow::Cow::Borrowed(rep.as_str()),
            ));
        }
        if let Some(ref card) = self.peer_card {
            msgs.push((
                "peer_card",
                std::borrow::Cow::Owned(Self::format_peer_card(card)),
            ));
        }
        if let Some(ref summary) = self.summary {
            msgs.push((
                "summary",
                std::borrow::Cow::Borrowed(summary.content.as_str()),
            ));
        }
        msgs
    }

    /// Build a provider message list.
    ///
    /// Shared by [`Self::to_openai`] and [`Self::to_anthropic`]: it emits the
    /// tag-wrapped context messages with the given `context_role` (escaping
    /// each value via [`escape_tag_value`] so session-derived content cannot
    /// break out of the `<tag>…</tag>` framing), then delegates per-message
    /// rendering to `render_message`, which receives the message and whether it
    /// belongs to the assistant.
    fn build_messages(
        &self,
        context_role: &'static str,
        assistant: &str,
        render_message: impl Fn(&super::message::MessageResponse, bool) -> serde_json::Value,
    ) -> Vec<serde_json::Value> {
        let mut result: Vec<serde_json::Value> = Vec::with_capacity(self.len());
        for (tag, value) in self.build_context_messages() {
            let value = escape_tag_value(&value);
            result.push(serde_json::json!({
                "role": context_role,
                "content": format!("<{tag}>{value}</{tag}>"),
            }));
        }
        for message in &self.messages {
            let is_assistant = message.peer_id == assistant;
            result.push(render_message(message, is_assistant));
        }
        result
    }

    /// Convert the context to OpenAI-compatible message format.
    ///
    /// System messages (`peer_representation`, `peer_card`, summary) are prepended.
    /// Assistant messages get `role: "assistant"`, all others get `role: "user"`.
    /// Each message also includes a `"name"` field set to the peer ID.
    ///
    /// `assistant` can be a `&str`, `String`, or `&Peer`.
    ///
    /// ```
    /// use honcho_ai::types::session::SessionContext;
    /// let ctx: SessionContext = serde_json::from_value(serde_json::json!({
    ///     "id": "s1",
    ///     "messages": [],
    /// })).unwrap();
    /// let messages = ctx.to_openai("assistant-1");
    /// assert!(messages.is_empty());
    /// ```
    #[must_use]
    #[allow(clippy::needless_pass_by_value)]
    pub fn to_openai(&self, assistant: impl IntoAssistantRef) -> Vec<serde_json::Value> {
        let assistant = assistant.as_assistant_name();
        self.build_messages("system", assistant, |message, is_assistant| {
            serde_json::json!({
                "role": if is_assistant { "assistant" } else { "user" },
                "name": message.peer_id,
                "content": message.content,
            })
        })
    }

    /// Convert the context to Anthropic-compatible message format.
    ///
    /// System-like messages (`peer_representation`, `peer_card`, summary) use `role: "user"`
    /// since Anthropic uses a separate `system` parameter.
    /// Assistant messages get `role: "assistant"`, others get `role: "user"` with
    /// `PEER_ID: CONTENT` format.
    ///
    /// `assistant` can be a `&str`, `String`, or `&Peer`.
    #[must_use]
    #[allow(clippy::needless_pass_by_value)]
    pub fn to_anthropic(&self, assistant: impl IntoAssistantRef) -> Vec<serde_json::Value> {
        let assistant = assistant.as_assistant_name();
        self.build_messages("user", assistant, |message, is_assistant| {
            if is_assistant {
                serde_json::json!({
                    "role": "assistant",
                    "content": message.content,
                })
            } else {
                serde_json::json!({
                    "role": "user",
                    "content": format!("{}: {}", message.peer_id, message.content),
                })
            }
        })
    }

    /// Returns the number of entries that `to_openai` / `to_anthropic` would produce.
    #[must_use]
    pub fn len(&self) -> usize {
        self.messages.len()
            + usize::from(self.summary.is_some())
            + usize::from(self.peer_representation.is_some())
            + usize::from(self.peer_card.is_some())
    }

    /// Returns `true` if the context contains no messages, summary,
    /// peer representation, or peer card.
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.messages.is_empty()
            && self.summary.is_none()
            && self.peer_representation.is_none()
            && self.peer_card.is_none()
    }
}