everruns-contracts 0.45.0

// RuntimeMessage is a DB-agnostic message type that represents
// a single message in the conversation history.
//
// Content is stored as Vec<ContentPart> for unified representation
// across storage and runtime layers.

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

use crate::runtime::typed_id::{FileId, ImageId, MessageId, ModelId};

#[cfg(feature = "openapi")]
use utoipa::ToSchema;

use crate::execution_phase::{ExecutionPhase, PhaseSource};
use crate::message::ProviderOpaqueContent;
use crate::reasoning::ReasoningContentPart;
mod turn_scope;
/// Message role in the conversation
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
// The Rust name is the published schema name. The REST API exposes only `user`
// and `agent` (`api::messages::MessageRole`); publishing this four-variant
// runtime enum as plain `MessageRole` made clients model roles the API never
// returns.
#[serde(rename_all = "snake_case")]
pub enum RuntimeMessageRole {
    /// System message (instructions)
    System,
    /// User message
    User,
    /// Agent response (may contain tool calls in content)
    Agent,
    /// Tool execution result
    ToolResult,
}

impl std::fmt::Display for RuntimeMessageRole {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            RuntimeMessageRole::System => write!(f, "system"),
            RuntimeMessageRole::User => write!(f, "user"),
            RuntimeMessageRole::Agent => write!(f, "agent"),
            RuntimeMessageRole::ToolResult => write!(f, "tool_result"),
        }
    }
}

impl From<&str> for RuntimeMessageRole {
    fn from(s: &str) -> Self {
        match s.to_lowercase().as_str() {
            "system" => RuntimeMessageRole::System,
            "user" => RuntimeMessageRole::User,
            // Accept both "agent" and legacy "assistant"
            "agent" | "assistant" => RuntimeMessageRole::Agent,
            "tool_result" => RuntimeMessageRole::ToolResult,
            _ => RuntimeMessageRole::User,
        }
    }
}

// ============================================
// External Actor (channel-agnostic user identity)
// ============================================

/// External actor identity for messages originating from external channels
/// (Slack, Discord, Teams, etc.).
///
/// Channel adapters populate this to identify the sender without coupling
/// core logic to any specific channel. The ReasonAtom uses this to prefix
/// user messages so the LLM knows who is speaking.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
pub struct ExternalActor {
    /// Opaque actor identifier from the source channel (e.g. Slack user ID "U0123456789")
    pub actor_id: String,
    /// Resolved display name (e.g. "Alice"). Falls back to actor_id if absent.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub actor_name: Option<String>,
    /// Source channel identifier (e.g. "slack", "discord")
    pub source: String,
    /// Channel-specific metadata (e.g. team_id, channel_id)
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub metadata: Option<std::collections::HashMap<String, String>>,
}

impl ExternalActor {
    /// Human-readable label: display name if available, otherwise actor_id.
    pub fn display_label(&self) -> &str {
        self.actor_name.as_deref().unwrap_or(&self.actor_id)
    }
}

// ============================================
// Controls (runtime options for message processing)
// ============================================

/// Reasoning configuration for the model
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
pub struct ReasoningConfig {
    /// Effort level for reasoning.
    ///
    /// Typed rather than free-form: the effort taxonomy is closed, and each
    /// driver previously re-parsed the string with its own case handling, which
    /// let `minimal` silently mean "no reasoning" on budget-based models.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub effort: Option<crate::model::ReasoningEffort>,
}

/// Runtime controls for message processing
#[derive(Debug, Clone, Serialize, Deserialize, Default, PartialEq)]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
pub struct Controls {
    /// Model ID to use for this message (format: model_{32-hex}).
    /// Overrides session and agent model settings.
    #[serde(skip_serializing_if = "Option::is_none")]
    #[cfg_attr(feature = "openapi", schema(value_type = Option<String>, example = "model_01933b5a00007000800000000000001"))]
    pub model_id: Option<ModelId>,

    /// Locale override for this message turn (BCP 47, e.g. `uk-UA`).
    /// Overrides the session locale for backend-authored strings and prompts.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub locale: Option<String>,

    /// Reasoning configuration
    #[serde(skip_serializing_if = "Option::is_none")]
    pub reasoning: Option<ReasoningConfig>,

    /// Speed (service tier) for this message turn: "flex", "default",
    /// "priority", "fast" (OpenAI's newer name for priority) or "ultrafast".
    /// Only sent when the model's profile lists the tier (OpenAI
    /// `service_tier`); otherwise the runtime drops it.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub speed: Option<String>,

    /// Verbosity for this message turn: "low", "medium", or "high". Only sent
    /// to providers whose model profile advertises a verbosity config (OpenAI
    /// `verbosity`).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub verbosity: Option<String>,

    /// Error disclosure override for this turn: "generic", "standard", or
    /// "detailed". Clamped to at most the mode allowed by the agent's
    /// `error_disclosure` capability (capability absent => "standard"), so a
    /// client can narrow but never widen disclosure.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub error_disclosure: Option<String>,

    /// Generic client hints — arbitrary key-value pairs declared by the client.
    /// Session-level defaults are set at session creation; per-message values
    /// override session hints key-by-key (shallow merge).
    ///
    /// Examples: `{"setup_connection": true, "rich_media": true}`
    #[serde(default, skip_serializing_if = "Option::is_none")]
    #[cfg_attr(feature = "openapi", schema(value_type = Option<Object>))]
    pub hints: Option<std::collections::HashMap<String, serde_json::Value>>,
}

impl Controls {
    /// Resolve effective hints by shallow-merging session-level defaults with
    /// per-message overrides. Per-message hints take precedence key-by-key.
    pub fn resolve_hints(
        session_hints: Option<&std::collections::HashMap<String, serde_json::Value>>,
        message_hints: Option<&std::collections::HashMap<String, serde_json::Value>>,
    ) -> std::collections::HashMap<String, serde_json::Value> {
        match (session_hints, message_hints) {
            (None, None) => std::collections::HashMap::new(),
            (Some(s), None) => s.clone(),
            (None, Some(m)) => m.clone(),
            (Some(s), Some(m)) => {
                let mut merged = s.clone();
                merged.extend(m.iter().map(|(k, v)| (k.clone(), v.clone())));
                merged
            }
        }
    }
}

/// A message in the conversation
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
// The canonical runtime/event message, and the Rust name is the published
// schema name. Distinct from the REST resource `api::messages::Message` (which
// adds `session_id` and `sequence`) and from the request-shaped
// `crate::driver_registry::Message` a driver sends upstream; both
// of the first two once claimed plain `Message` in one OpenAPI document, so
// generated clients saw whichever won.
pub struct RuntimeMessage {
    /// Unique message ID (format: message_{32-hex})
    #[cfg_attr(feature = "openapi", schema(value_type = String, example = "message_01933b5a00007000800000000000001"))]
    pub id: MessageId,

    /// Message role
    pub role: RuntimeMessageRole,

    /// Message content as array of content parts (text, images, tool calls, tool results)
    pub content: Vec<ContentPart>,

    /// Execution phase for this message.
    ///
    /// Helps LLMs distinguish between intermediate working commentary and completed
    /// answers in multi-step tool-calling flows. Only set on agent (assistant) messages.
    /// Providers with native phase support (OpenAI GPT-5.x) send this value in the API
    /// request; others derive it from state but don't send it to the provider.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub phase: Option<ExecutionPhase>,

    /// Whether [`Self::phase`] was reported by the provider or inferred from
    /// tool-call presence. A derived phase carries no information beyond
    /// "this message called tools", so consumers that need a real
    /// classification must be able to tell the two apart.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub phase_source: Option<PhaseSource>,

    /// Runtime controls (model, reasoning, etc.)
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub controls: Option<Controls>,

    /// Message-level metadata
    #[serde(default, skip_serializing_if = "Option::is_none")]
    #[cfg_attr(feature = "openapi", schema(value_type = Option<Object>))]
    pub metadata: Option<std::collections::HashMap<String, serde_json::Value>>,

    /// External actor identity (for messages from external channels like Slack)
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub external_actor: Option<ExternalActor>,

    /// Timestamp when the message was created
    pub created_at: DateTime<Utc>,
}

// ============================================
// Content Type Enum
// ============================================

/// Content type discriminator
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
#[serde(rename_all = "snake_case")]
pub enum ContentType {
    Text,
    Image,
    ImageFile,
    /// Generic file attachment (for example a PDF).
    File,
    ToolCall,
    ToolResult,
    Reasoning,
    /// Provider-native content retained only for internal replay.
    ProviderOpaque,
}

impl std::fmt::Display for ContentType {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            ContentType::Text => write!(f, "text"),
            ContentType::Image => write!(f, "image"),
            ContentType::ImageFile => write!(f, "image_file"),
            ContentType::File => write!(f, "file"),
            ContentType::ToolCall => write!(f, "tool_call"),
            ContentType::ToolResult => write!(f, "tool_result"),
            ContentType::Reasoning => write!(f, "reasoning"),
            ContentType::ProviderOpaque => write!(f, "provider_opaque"),
        }
    }
}

impl From<&str> for ContentType {
    fn from(s: &str) -> Self {
        match s {
            "image" => ContentType::Image,
            "image_file" => ContentType::ImageFile,
            "tool_call" => ContentType::ToolCall,
            "tool_result" => ContentType::ToolResult,
            "reasoning" => ContentType::Reasoning,
            "provider_opaque" => ContentType::ProviderOpaque,
            _ => ContentType::Text,
        }
    }
}

// ============================================
// Content Part Structs
// ============================================

/// Text content part
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
pub struct TextContentPart {
    pub text: String,
    /// Claim-level citations attached to spans of `text`.
    ///
    /// The narrow render contract shared by all citation capabilities. Empty for non-cited text, so the wire shape of
    /// existing messages is unchanged.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub annotations: Vec<TextAnnotation>,
}

impl TextContentPart {
    pub fn new(text: impl Into<String>) -> Self {
        Self {
            text: text.into(),
            annotations: Vec::new(),
        }
    }

    /// Attach citation annotations, replacing any existing ones.
    pub fn with_annotations(mut self, annotations: Vec<TextAnnotation>) -> Self {
        self.annotations = annotations;
        self
    }
}

/// A claim-level citation attached to a span of generated text.
///
/// The single shared type across every citation capability: a text span linked
/// to a source. Producers agree only on this render contract — each capability
/// keeps its own richer representation (e.g. `KnowledgeIndexCitation`) and maps
/// into this envelope at emit time.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
pub struct TextAnnotation {
    /// 0-indexed start char offset into the enclosing `TextContentPart.text`.
    #[cfg_attr(feature = "openapi", schema(example = 0))]
    pub start: usize,
    /// Exclusive end char offset.
    #[cfg_attr(feature = "openapi", schema(example = 19))]
    pub end: usize,
    /// Capability id that produced this annotation (e.g. `citation_retrieval`).
    /// Lets the UI and evals attribute and filter each citation by feed.
    #[cfg_attr(feature = "openapi", schema(example = "citation_retrieval"))]
    pub origin: String,
    /// The cited source.
    pub source: AnnotationSource,
    /// Opaque producer id (e.g. `kchk_…`, `kbe_…`, a URL hash). Not interpreted
    /// by the render contract.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    #[cfg_attr(feature = "openapi", schema(example = "kchk_01j9y3q8w2"))]
    pub external_id: Option<String>,
    /// Verification verdict, filled by the `citation_verification` capability.
    /// Absent means unverified (not "unsupported").
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub verified: Option<VerificationVerdict>,
}

/// The source a [`TextAnnotation`] points to.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
pub struct AnnotationSource {
    /// Stable, linkable locator (e.g. `github://owner/repo@main/docs/x.md` or an
    /// `https://` URL).
    #[cfg_attr(
        feature = "openapi",
        schema(example = "github://owner/repo@main/docs/x.md")
    )]
    pub uri: String,
    /// Human-readable source title, when known.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    #[cfg_attr(feature = "openapi", schema(example = "Architecture Overview"))]
    pub title: Option<String>,
    /// Trimmed passage that backs the claim. Display-only; never relied on for
    /// prompt reconstruction.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    #[cfg_attr(
        feature = "openapi",
        schema(example = "The control plane owns durable state.")
    )]
    pub snippet: Option<String>,
    /// Provenance within the document (line / char / page / block ranges),
    /// reusing the retrieval `location` JSONB shape.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub location: Option<serde_json::Value>,
}

/// Outcome of citation verification (see the `citation_verification` capability).
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
pub struct VerificationVerdict {
    /// Whether the cited source supports the claim.
    pub status: VerificationStatus,
    /// Entailment confidence in `[0, 1]`, when the verifier produced one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    #[cfg_attr(feature = "openapi", schema(example = 0.92))]
    pub score: Option<f32>,
}

/// Whether a cited source entails the claim it is attached to.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
#[cfg_attr(feature = "openapi", schema(example = "entailed"))]
#[serde(rename_all = "snake_case")]
pub enum VerificationStatus {
    /// The source supports the claim.
    Entailed,
    /// The source does not support the claim.
    Unsupported,
    /// The verifier could not decide.
    Uncertain,
}

/// Image content part (base64 or URL)
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
pub struct ImageContentPart {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub url: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub base64: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub media_type: Option<String>,
}

impl ImageContentPart {
    pub fn from_url(url: impl Into<String>) -> Self {
        Self {
            url: Some(url.into()),
            base64: None,
            media_type: None,
        }
    }

    pub fn from_base64(base64: impl Into<String>, media_type: impl Into<String>) -> Self {
        Self {
            url: None,
            base64: Some(base64.into()),
            media_type: Some(media_type.into()),
        }
    }
}

/// Image file content part (reference to uploaded image)
///
/// This is used for images uploaded via the /images API.
/// The image data is stored separately and referenced by ID.
/// Note: Currently filtered out before sending to LLM.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
pub struct ImageFileContentPart {
    /// ID of the uploaded image (format: img_{32-hex})
    #[cfg_attr(feature = "openapi", schema(value_type = String, example = "img_01933b5a00007000800000000000001"))]
    pub image_id: ImageId,
    /// Original filename (for display)
    #[serde(skip_serializing_if = "Option::is_none")]
    pub filename: Option<String>,
}

impl ImageFileContentPart {
    pub fn new(image_id: ImageId) -> Self {
        Self {
            image_id,
            filename: None,
        }
    }

    pub fn with_filename(image_id: ImageId, filename: impl Into<String>) -> Self {
        Self {
            image_id,
            filename: Some(filename.into()),
        }
    }
}

/// File content part (reference to an uploaded file, e.g. a PDF)
///
/// This is used for files uploaded via the /files API.
/// The file data is stored separately and referenced by ID.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
pub struct FileContentPart {
    /// ID of the uploaded file (format: file_{32-hex})
    #[cfg_attr(feature = "openapi", schema(value_type = String, example = "file_01933b5a00007000800000000000001"))]
    pub file_id: FileId,
    /// Original filename (for display and provider file parts)
    #[serde(skip_serializing_if = "Option::is_none")]
    pub filename: Option<String>,
}

impl FileContentPart {
    /// Create a file content part that references an already-stored file.
    pub fn new(file_id: FileId) -> Self {
        Self {
            file_id,
            filename: None,
        }
    }

    /// Create a file content part with its original filename attached.
    pub fn with_filename(file_id: FileId, filename: impl Into<String>) -> Self {
        Self {
            file_id,
            filename: Some(filename.into()),
        }
    }
}

/// Tool call content part (assistant requesting tool execution)
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
pub struct ToolCallContentPart {
    /// Original native call, including raw custom input and async metadata.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub native: Option<crate::native_async::NativeToolCall>,
    pub id: String,
    pub name: String,
    pub arguments: serde_json::Value,
}

impl ToolCallContentPart {
    /// Validate and retain a native call alongside its portable tool arguments.
    pub fn from_native(
        call: crate::native_async::NativeToolCall,
    ) -> crate::runtime::error::Result<Self> {
        use crate::native_async::NativeToolCall;
        call.validate()?;
        let arguments = match &call {
            NativeToolCall::Function { arguments, .. } => serde_json::from_str(arguments)
                .map_err(|error| crate::runtime::error::AgentLoopError::llm(error.to_string()))?,
            NativeToolCall::Custom { input, .. } => serde_json::Value::String(input.clone()),
        };
        Ok(Self {
            id: call.id().into(),
            name: call.name().into(),
            arguments,
            native: Some(call),
        })
    }

    pub fn new(
        id: impl Into<String>,
        name: impl Into<String>,
        arguments: serde_json::Value,
    ) -> Self {
        Self {
            native: None,
            id: id.into(),
            name: name.into(),
            arguments,
        }
    }
}

/// Tool result content part (result of tool execution)
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
pub struct ToolResultContentPart {
    /// ID of the tool call this result corresponds to
    pub tool_call_id: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub result: Option<serde_json::Value>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub error: Option<String>,
}

impl ToolResultContentPart {
    pub fn new(
        tool_call_id: impl Into<String>,
        result: Option<serde_json::Value>,
        error: Option<String>,
    ) -> Self {
        Self {
            tool_call_id: tool_call_id.into(),
            result,
            error,
        }
    }

    pub fn success(tool_call_id: impl Into<String>, result: serde_json::Value) -> Self {
        Self {
            tool_call_id: tool_call_id.into(),
            result: Some(result),
            error: None,
        }
    }

    pub fn error(tool_call_id: impl Into<String>, error: impl Into<String>) -> Self {
        Self {
            tool_call_id: tool_call_id.into(),
            result: None,
            error: Some(error.into()),
        }
    }
}

// ============================================
// Content Part Enums
// ============================================

/// A part of message content - can be text, image, image_file, tool_call, or tool_result
///
/// This is the canonical content part type used across the system.
/// API layer enables the "openapi" feature to add ToSchema derive.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
#[serde(tag = "type", rename_all = "snake_case")]
#[non_exhaustive]
pub enum ContentPart {
    /// Text content
    Text(TextContentPart),
    /// Image content (base64 or URL)
    Image(ImageContentPart),
    /// Image file content (reference to uploaded image by ID)
    ImageFile(ImageFileContentPart),
    /// File content (reference to uploaded file, e.g. PDF, by ID)
    File(FileContentPart),
    /// Tool call content (assistant requesting tool execution)
    ToolCall(ToolCallContentPart),
    /// Tool result content (result of tool execution)
    ToolResult(ToolResultContentPart),
    /// Provider reasoning artifact, ordered against the text and tool calls it
    /// was interleaved with.
    Reasoning(ReasoningContentPart),
    /// Provider-native assistant content retained only for internal replay.
    ProviderOpaque(ProviderOpaqueContent),
}

impl ContentPart {
    /// Create a text content part
    pub fn text(text: impl Into<String>) -> Self {
        ContentPart::Text(TextContentPart::new(text))
    }

    /// Convert a JSON tool result into text without JSON-quoting string values.
    /// Structured values retain their JSON representation for transport and details views.
    pub fn tool_result_text(value: &serde_json::Value) -> Self {
        match value {
            serde_json::Value::String(text) => Self::text(text.clone()),
            other => Self::text(other.to_string()),
        }
    }

    /// Create an image content part from URL
    pub fn image_url(url: impl Into<String>) -> Self {
        ContentPart::Image(ImageContentPart::from_url(url))
    }

    /// Create an image file content part (reference to uploaded image)
    pub fn image_file(image_id: ImageId) -> Self {
        ContentPart::ImageFile(ImageFileContentPart::new(image_id))
    }

    /// Create a generic file content part (reference to an uploaded file).
    pub fn file(file_id: FileId) -> Self {
        ContentPart::File(FileContentPart::new(file_id))
    }

    /// Create a tool call content part
    pub fn tool_call(
        id: impl Into<String>,
        name: impl Into<String>,
        arguments: serde_json::Value,
    ) -> Self {
        ContentPart::ToolCall(ToolCallContentPart::new(id, name, arguments))
    }

    /// Create a tool result content part
    pub fn tool_result(
        tool_call_id: impl Into<String>,
        result: Option<serde_json::Value>,
        error: Option<String>,
    ) -> Self {
        ContentPart::ToolResult(ToolResultContentPart::new(tool_call_id, result, error))
    }

    /// Create a reasoning content part
    pub fn reasoning(part: ReasoningContentPart) -> Self {
        ContentPart::Reasoning(part)
    }

    /// Get the reasoning artifact if this is a reasoning part
    pub fn as_reasoning(&self) -> Option<&ReasoningContentPart> {
        match self {
            ContentPart::Reasoning(r) => Some(r),
            _ => None,
        }
    }

    /// Whether this part is a reasoning artifact.
    pub fn is_reasoning(&self) -> bool {
        matches!(self, ContentPart::Reasoning(_))
    }

    /// Get text if this is a text part
    pub fn as_text(&self) -> Option<&str> {
        match self {
            ContentPart::Text(t) => Some(&t.text),
            _ => None,
        }
    }

    /// Check if this is an ImageFile part
    pub fn is_image_file(&self) -> bool {
        matches!(self, ContentPart::ImageFile(_))
    }

    /// Returns true when this is a generic file part.
    pub fn is_file(&self) -> bool {
        matches!(self, ContentPart::File(_))
    }

    /// Get the content type
    pub fn content_type(&self) -> ContentType {
        match self {
            ContentPart::Text(_) => ContentType::Text,
            ContentPart::Image(_) => ContentType::Image,
            ContentPart::ImageFile(_) => ContentType::ImageFile,
            ContentPart::File(_) => ContentType::File,
            ContentPart::ToolCall(_) => ContentType::ToolCall,
            ContentPart::ToolResult(_) => ContentType::ToolResult,
            ContentPart::Reasoning(_) => ContentType::Reasoning,
            ContentPart::ProviderOpaque(_) => ContentType::ProviderOpaque,
        }
    }

    /// Convert content part to OpenAI-compatible format
    ///
    /// Returns `None` for content types that aren't valid in user/system messages
    /// (ImageFile, ToolCall, ToolResult are handled at message level).
    pub fn to_openai_format(&self) -> Option<serde_json::Value> {
        match self {
            ContentPart::Text(t) => Some(serde_json::json!({
                "type": "text",
                "text": t.text
            })),
            ContentPart::Image(img) => {
                if let Some(url) = &img.url {
                    Some(serde_json::json!({
                        "type": "image_url",
                        "image_url": { "url": url }
                    }))
                } else if let Some(b64) = &img.base64 {
                    let media_type = img.media_type.as_deref().unwrap_or("image/png");
                    Some(serde_json::json!({
                        "type": "image_url",
                        "image_url": { "url": format!("data:{};base64,{}", media_type, b64) }
                    }))
                } else {
                    None
                }
            }
            // ImageFile, ToolCall, ToolResult handled at message level
            _ => None,
        }
    }
}

/// Input content part - text, image, and image_file (for user input)
///
/// This is a subset of ContentPart that users can send.
/// Tool calls and results are system-generated.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum InputContentPart {
    /// Text content
    Text(TextContentPart),
    /// Image content (base64 or URL)
    Image(ImageContentPart),
    /// Image file content (reference to uploaded image by ID)
    ImageFile(ImageFileContentPart),
    /// File content (reference to uploaded file, e.g. PDF, by ID)
    File(FileContentPart),
}

impl From<InputContentPart> for ContentPart {
    fn from(input: InputContentPart) -> Self {
        match input {
            InputContentPart::Text(t) => ContentPart::Text(t),
            InputContentPart::Image(i) => ContentPart::Image(i),
            InputContentPart::ImageFile(f) => ContentPart::ImageFile(f),
            InputContentPart::File(f) => ContentPart::File(f),
        }
    }
}

impl InputContentPart {
    /// Create a text content part
    pub fn text(text: impl Into<String>) -> Self {
        InputContentPart::Text(TextContentPart::new(text))
    }

    /// Create an image content part from URL
    pub fn image_url(url: impl Into<String>) -> Self {
        InputContentPart::Image(ImageContentPart::from_url(url))
    }

    /// Create an image file content part (reference to uploaded image)
    pub fn image_file(image_id: ImageId) -> Self {
        InputContentPart::ImageFile(ImageFileContentPart::new(image_id))
    }

    /// Create a generic file input part (reference to an uploaded file).
    pub fn file(file_id: FileId) -> Self {
        InputContentPart::File(FileContentPart::new(file_id))
    }

    /// Get text content if this is a Text part
    pub fn as_text(&self) -> Option<&str> {
        match self {
            InputContentPart::Text(t) => Some(&t.text),
            _ => None,
        }
    }

    /// Get the content type
    pub fn content_type(&self) -> ContentType {
        match self {
            InputContentPart::Text(_) => ContentType::Text,
            InputContentPart::Image(_) => ContentType::Image,
            InputContentPart::ImageFile(_) => ContentType::ImageFile,
            InputContentPart::File(_) => ContentType::File,
        }
    }
}

/// Message metadata key naming where a user-role message came from when no
/// person wrote it. Reserved: client-supplied metadata loses this key, so only
/// the platform can set it.
pub const MESSAGE_ORIGIN_METADATA_KEY: &str = "everruns_origin";
/// Origin of a message the platform injects to wake a session about its tasks
/// (a thread finished, asked a question, or sent an update).
pub const MESSAGE_ORIGIN_TASK_WAKE: &str = "task_wake";

/// Metadata for a platform-injected task wake-up message.
pub fn task_wake_message_metadata() -> std::collections::HashMap<String, serde_json::Value> {
    std::collections::HashMap::from([(
        MESSAGE_ORIGIN_METADATA_KEY.to_string(),
        serde_json::Value::String(MESSAGE_ORIGIN_TASK_WAKE.to_string()),
    )])
}

/// Remove reserved platform keys from caller-supplied message metadata, so a
/// client cannot make its own text look like a platform notice.
pub fn strip_reserved_message_metadata(
    metadata: &mut Option<std::collections::HashMap<String, serde_json::Value>>,
) {
    if let Some(map) = metadata.as_mut() {
        map.remove(MESSAGE_ORIGIN_METADATA_KEY);
        if map.is_empty() {
            *metadata = None;
        }
    }
}

impl RuntimeMessage {
    /// Platform origin of a user-role message no person wrote, if any.
    pub fn origin(&self) -> Option<&str> {
        self.metadata
            .as_ref()?
            .get(MESSAGE_ORIGIN_METADATA_KEY)?
            .as_str()
    }

    /// Whether the platform injected this message to report task activity.
    pub fn is_task_wake(&self) -> bool {
        self.origin() == Some(MESSAGE_ORIGIN_TASK_WAKE)
    }

    /// Reasoning artifacts carried by this message, in emission order.
    pub fn reasoning_parts(&self) -> impl Iterator<Item = &ReasoningContentPart> {
        self.content.iter().filter_map(ContentPart::as_reasoning)
    }

    /// Whether this message carries any provider reasoning artifact.
    pub fn has_reasoning(&self) -> bool {
        self.content.iter().any(ContentPart::is_reasoning)
    }

    /// Readable reasoning across every artifact, joined for display.
    ///
    /// Display only. Replay must walk [`RuntimeMessage::reasoning_parts`] so each
    /// artifact keeps its own signature and position.
    pub fn reasoning_display_text(&self) -> Option<String> {
        let joined = self
            .reasoning_parts()
            .filter_map(ReasoningContentPart::display_text)
            .collect::<Vec<_>>()
            .join("\n\n");
        (!joined.is_empty()).then_some(joined)
    }

    /// Replace every reasoning part with its publishable projection, dropping
    /// opaque provider replay state. Used at API boundaries.
    pub fn into_public(mut self) -> Self {
        self.content
            .retain(|part| !matches!(part, ContentPart::ProviderOpaque(_)));
        for part in &mut self.content {
            if let ContentPart::Reasoning(r) = part {
                *r = r.to_public();
            }
        }
        self
    }

    /// Override the generated message id.
    ///
    /// Streaming producers use this to allocate a public id before emitting
    /// `output.message.started`, then reuse it on the completed message.
    pub fn with_id(mut self, id: MessageId) -> Self {
        self.id = id;
        self
    }

    /// Create a new user message
    pub fn user(content: impl Into<String>) -> Self {
        Self {
            id: MessageId::new(),
            role: RuntimeMessageRole::User,
            content: vec![ContentPart::text(content)],
            phase: None,
            phase_source: None,
            controls: None,
            metadata: None,
            external_actor: None,
            created_at: Utc::now(),
        }
    }

    /// Create a new assistant message
    pub fn assistant(content: impl Into<String>) -> Self {
        Self {
            id: MessageId::new(),
            role: RuntimeMessageRole::Agent,
            content: vec![ContentPart::text(content)],
            phase: None,
            phase_source: None,
            controls: None,
            metadata: None,
            external_actor: None,
            created_at: Utc::now(),
        }
    }

    /// Create a new assistant message with tool calls
    ///
    /// Tool calls are stored as ContentPart::ToolCall in the content array
    /// alongside the text content. Empty text content is omitted to avoid
    /// LLM API errors (e.g., Anthropic requires non-empty text blocks).
    pub fn assistant_with_tools(
        content: impl Into<String>,
        tool_calls: Vec<crate::runtime::tool_types::ToolCall>,
    ) -> Self {
        let text_content = content.into();
        let mut parts = Vec::new();
        // Only include text part if non-empty
        if !text_content.is_empty() {
            parts.push(ContentPart::text(text_content));
        }
        for tc in tool_calls {
            parts.push(ContentPart::ToolCall(ToolCallContentPart {
                native: None,
                id: tc.id,
                name: tc.name,
                arguments: tc.arguments,
            }));
        }
        Self {
            id: MessageId::new(),
            role: RuntimeMessageRole::Agent,
            content: parts,
            phase: None,
            phase_source: None,
            controls: None,
            metadata: None,
            external_actor: None,
            created_at: Utc::now(),
        }
    }

    /// Create a new system message
    pub fn system(content: impl Into<String>) -> Self {
        Self {
            id: MessageId::new(),
            role: RuntimeMessageRole::System,
            content: vec![ContentPart::text(content)],
            phase: None,
            phase_source: None,
            controls: None,
            metadata: None,
            external_actor: None,
            created_at: Utc::now(),
        }
    }

    /// Create a tool result message
    pub fn tool_result(
        tool_call_id: impl Into<String>,
        result: Option<serde_json::Value>,
        error: Option<String>,
    ) -> Self {
        let tool_call_id = tool_call_id.into();
        Self {
            id: MessageId::new(),
            role: RuntimeMessageRole::ToolResult,
            content: vec![ContentPart::ToolResult(ToolResultContentPart::new(
                tool_call_id,
                result,
                error,
            ))],
            phase: None,
            phase_source: None,
            controls: None,
            metadata: None,
            external_actor: None,
            created_at: Utc::now(),
        }
    }

    /// Create a tool result message with images.
    ///
    /// Images are included as `ContentPart::Image` alongside the `ToolResult` part.
    /// When converted to the provider `Message`, images become native image content blocks
    /// that the LLM can see visually (not just stringified base64).
    pub fn tool_result_with_images(
        tool_call_id: impl Into<String>,
        result: Option<serde_json::Value>,
        images: Vec<crate::tool_types::ToolResultImage>,
    ) -> Self {
        let tool_call_id = tool_call_id.into();
        let mut content = vec![ContentPart::ToolResult(ToolResultContentPart::new(
            tool_call_id,
            result,
            None,
        ))];
        for img in images {
            content.push(ContentPart::Image(ImageContentPart::from_base64(
                img.base64,
                img.media_type,
            )));
        }
        Self {
            id: MessageId::new(),
            role: RuntimeMessageRole::ToolResult,
            content,
            phase: None,
            phase_source: None,
            controls: None,
            metadata: None,
            external_actor: None,
            created_at: Utc::now(),
        }
    }

    /// Set the execution phase on this message and return self.
    pub fn with_phase(mut self, phase: ExecutionPhase) -> Self {
        self.phase = Some(phase);
        self
    }

    /// Set the phase together with where it came from.
    pub fn with_phase_from(mut self, phase: ExecutionPhase, source: PhaseSource) -> Self {
        self.phase = Some(phase);
        self.phase_source = Some(source);
        self
    }

    /// Get the tool_call_id from a tool result message
    ///
    /// Returns the tool_call_id from the first ToolResult content part, if any.
    pub fn tool_call_id(&self) -> Option<&str> {
        self.content.iter().find_map(|p| match p {
            ContentPart::ToolResult(tr) => Some(tr.tool_call_id.as_str()),
            _ => None,
        })
    }

    /// Get first text content from the message
    pub fn text(&self) -> Option<&str> {
        self.content.iter().find_map(|p| p.as_text())
    }

    /// Get all tool calls from the message content
    pub fn tool_calls(&self) -> Vec<&ToolCallContentPart> {
        self.content
            .iter()
            .filter_map(|p| match p {
                ContentPart::ToolCall(tc) => Some(tc),
                _ => None,
            })
            .collect()
    }

    /// Check if this message has tool calls
    pub fn has_tool_calls(&self) -> bool {
        self.content
            .iter()
            .any(|p| matches!(p, ContentPart::ToolCall(_)))
    }

    /// Get the first tool result from the message content
    pub fn tool_result_content(&self) -> Option<&ToolResultContentPart> {
        self.content.iter().find_map(|p| match p {
            ContentPart::ToolResult(tr) => Some(tr),
            _ => None,
        })
    }

    /// Convert content to LLM-compatible string representation
    pub fn content_to_llm_string(&self) -> String {
        self.content
            .iter()
            .map(|part| match part {
                ContentPart::Text(t) => t.text.clone(),
                // Reasoning is replayed as provider-native artifacts on
                // the provider `Message::reasoning`; it must never be flattened into
                // prompt text. Filtered out below.
                ContentPart::Reasoning(_) => String::new(),
                ContentPart::ProviderOpaque(_) => String::new(),
                ContentPart::Image(_) => "[Image]".to_string(),
                ContentPart::ImageFile(_) => "[Image File]".to_string(),
                ContentPart::File(part) => part
                    .filename
                    .clone()
                    .map(|n| format!("[PDF File: {}]", n))
                    .unwrap_or_else(|| "[PDF File]".to_string()),
                ContentPart::ToolCall(tc) => {
                    format!(
                        "Tool call: {} with arguments: {}",
                        tc.name,
                        serde_json::to_string(&tc.arguments).unwrap_or_default()
                    )
                }
                ContentPart::ToolResult(tr) => {
                    if let Some(err) = &tr.error {
                        format!("Tool error: {}", err)
                    } else if let Some(res) = &tr.result {
                        serde_json::to_string(res).unwrap_or_else(|_| "{}".to_string())
                    } else {
                        "{}".to_string()
                    }
                }
            })
            .filter(|rendered| !rendered.is_empty())
            .collect::<Vec<_>>()
            .join("\n")
    }

    /// Convert message to OpenAI-compatible format
    ///
    /// Transforms internal message format to OpenAI API format:
    /// - `agent` role → `assistant`
    /// - `tool_result` role → `tool` (with tool_call_id at message level)
    /// - Tool calls formatted as `{id, type: "function", function: {name, arguments}}`
    ///
    /// Used by observability backends (e.g., Braintrust) that expect OpenAI format.
    pub fn to_openai_format(&self) -> serde_json::Value {
        let role = match self.role {
            RuntimeMessageRole::System => "system",
            RuntimeMessageRole::User => "user",
            RuntimeMessageRole::Agent => "assistant",
            RuntimeMessageRole::ToolResult => "tool",
        };

        // Handle tool result messages (need tool_call_id at message level)
        if self.role == RuntimeMessageRole::ToolResult {
            let tool_call_id = self.tool_call_id().unwrap_or("");
            let content = self
                .content
                .iter()
                .find_map(|p| match p {
                    ContentPart::ToolResult(tr) => {
                        if let Some(error) = &tr.error {
                            Some(format!("Error: {}", error))
                        } else if let Some(result) = &tr.result {
                            Some(serde_json::to_string(result).unwrap_or_else(|_| "{}".to_string()))
                        } else {
                            Some("{}".to_string())
                        }
                    }
                    _ => None,
                })
                .unwrap_or_else(|| "{}".to_string());

            return serde_json::json!({
                "role": role,
                "content": content,
                "tool_call_id": tool_call_id
            });
        }

        // Handle assistant messages with tool calls
        if self.role == RuntimeMessageRole::Agent {
            let tool_calls: Vec<serde_json::Value> = self
                .content
                .iter()
                .filter_map(|p| match p {
                    ContentPart::ToolCall(tc) => Some(serde_json::json!({
                        "id": tc.id,
                        "type": "function",
                        "function": {
                            "name": tc.name,
                            "arguments": serde_json::to_string(&tc.arguments).unwrap_or_else(|_| "{}".to_string())
                        }
                    })),
                    _ => None,
                })
                .collect();

            let text_content: String = self
                .content
                .iter()
                .filter_map(|p| match p {
                    ContentPart::Text(t) => Some(t.text.clone()),
                    _ => None,
                })
                .collect::<Vec<_>>()
                .join("\n");

            if tool_calls.is_empty() {
                return serde_json::json!({
                    "role": role,
                    "content": text_content
                });
            } else {
                let mut result = serde_json::json!({
                    "role": role,
                    "tool_calls": tool_calls
                });
                if !text_content.is_empty() {
                    result["content"] = serde_json::json!(text_content);
                }
                return result;
            }
        }

        // For system/user messages, convert content parts
        let content = self.content_to_openai_format();
        serde_json::json!({
            "role": role,
            "content": content
        })
    }

    /// Convert content parts to OpenAI-compatible format
    fn content_to_openai_format(&self) -> serde_json::Value {
        // Single text content → string
        if self.content.len() == 1
            && let ContentPart::Text(t) = &self.content[0]
        {
            return serde_json::json!(t.text);
        }

        // Convert each content part
        let parts: Vec<serde_json::Value> = self
            .content
            .iter()
            .filter_map(|part| part.to_openai_format())
            .collect();

        if parts.is_empty() {
            return serde_json::json!("");
        }

        // Single text part after filtering → string
        if parts.len() == 1
            && let Some(text) = parts[0].get("text")
        {
            return text.clone();
        }

        serde_json::json!(parts)
    }
}

/// Patch dangling tool calls by adding synthetic "cancelled" results.
///
/// This ensures every tool call has a corresponding tool result,
/// preventing LLM API errors (e.g., OpenAI requires every tool_call to have a result).
///
/// This is the simple, store-free patcher used by out-of-band completions
/// (see `crate::runtime::command_host`). The main reason path uses the durable-store-aware
/// the execution kernel's transcript-repair path instead (EVE-533),
/// which can replay settled results rather than synthesizing cancellations.
pub fn patch_dangling_tool_calls(messages: &[RuntimeMessage]) -> Vec<RuntimeMessage> {
    let mut result = Vec::new();

    for (i, msg) in messages.iter().enumerate() {
        result.push(msg.clone());

        // After an assistant message with tool calls, add cancelled results for any missing ones
        if msg.role == RuntimeMessageRole::Agent && msg.has_tool_calls() {
            for tc in msg.tool_calls() {
                // Look for a matching tool result in ALL subsequent messages
                let has_result = messages[(i + 1)..].iter().any(|m| {
                    m.role == RuntimeMessageRole::ToolResult && m.tool_call_id() == Some(&tc.id)
                });

                if !has_result {
                    result.push(RuntimeMessage::tool_result(
                        &tc.id,
                        None,
                        Some(
                            "cancelled - another message came in before it could be completed"
                                .to_string(),
                        ),
                    ));
                }
            }
        }
    }

    result
}

#[cfg(test)]
#[path = "message_tests.rs"]
mod tests;