Struct ChatMessage 

pub struct ChatMessage {
    pub role: Role,
    pub content: Option<String>,
    pub content_parts: Option<Vec<Value>>,
    pub tool_calls: Option<Vec<ToolCall>>,
    pub tool_call_id: Option<String>,
    pub name: Option<String>,
    pub metadata: BTreeMap<String, String>,
}

A single message in a conversation.

The field layout mirrors the OpenAI chat-completions wire format so it serializes directly with no conversion layer — which is exactly what OpenRouter and other OpenAI-compatible gateways consume.

Fields

role: Role

Author of the message.

content: Option<String>

Text content. None for assistant turns that are pure tool calls, or when Self::content_parts carries multimodal content instead.

content_parts: Option<Vec<Value>>

Multimodal content parts (e.g. {"type":"image_url", ...} alongside {"type":"text", ...}). When present, these are serialized as the wire content array (taking precedence over Self::content) — this is how images/vision input reach a vision model.

tool_calls: Option<Vec<ToolCall>>

Tool calls requested by an assistant turn.

tool_call_id: Option<String>

For tool messages: the id of the ToolCall this is a result for.

name: Option<String>

Optional name (used by some providers for tool messages).

metadata: BTreeMap<String, String>

Source-format provenance/labels that have no slot in the OpenAI wire shape (e.g. Codex phase, turn_id; Claude promptSource, isMeta, sourceToolAssistantUUID). Never serialized — kept only for fidelity and inspection so loading a session doesn’t silently discard this signal. (Never serialized — the custom Serialize impl omits it.)

Implementations

impl ChatMessage

pub fn system(content: impl Into<String>) -> Self

Build a system message.

pub fn user_with_images(text: impl Into<String>, image_urls: &[String]) -> Self

Build a user message with multimodal content — leading text plus one image_url part per URL (an https://… link or a data: URL). This is how images are passed to a vision model.

pub fn user(content: impl Into<String>) -> Self

Build a user message.

pub fn assistant(content: impl Into<String>) -> Self

Build an assistant message with plain text.

pub fn tool_result( tool_call_id: impl Into<String>, name: impl Into<String>, content: impl Into<String>, ) -> Self

Build a tool result message tied to a specific tool call.

pub fn tool_result_with_image( tool_call_id: impl Into<String>, name: impl Into<String>, notice: impl Into<String>, data_url: impl Into<String>, ) -> Self

P4c (COMPOSABLE-HARNESS-DESIGN.md §1.2 core.tools.read_file multimodal / view_image): a tool result that carries an image content block alongside a short text notice — content_parts (image passthrough) rather than a plain string, so the model actually sees the image. data_url is a full data:image/...; base64,... URL (see tools::builtins::image_tool_result).

pub fn tool_calls(&self) -> &[ToolCall]

The tool calls on this message, or an empty slice.

pub fn with_meta(self, key: impl Into<String>, value: impl Into<String>) -> Self

Attach a metadata key/value, returning self (builder style).

pub fn with_metas(self, pairs: &[(String, String)]) -> Self

Attach several metadata key/values, returning self.

Trait Implementations

impl Clone for ChatMessage

fn clone(&self) -> ChatMessage

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ChatMessage

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for ChatMessage

fn deserialize<D: Deserializer<'de>>(de: D) -> Result<Self, D::Error>

Deserialize this value from the given Serde deserializer.

impl From<&ChatMessage> for NativeTurn

fn from(msg: &ChatMessage) -> Self

Converts to this type from the input type.

impl PartialEq for ChatMessage

fn eq(&self, other: &ChatMessage) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for ChatMessage

fn serialize<S: Serializer>(&self, ser: S) -> Result<S::Ok, S::Error>

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for ChatMessage