systemprompt_models/a2a/
task_metadata.rs

1//! Lifecycle and accounting metadata for A2A tasks.
2//!
3//! [`TaskMetadata`] distinguishes the two [`TaskType`] flavours (MCP tool
4//! execution versus agent message), tracks timing and token usage, and carries
5//! an open-ended `extensions` map flattened into the serialized form. The
6//! `new_validated_*` constructors enforce the required-field contract before a
7//! task is recorded.
8//!
9//! Copyright (c) systemprompt.io — Business Source License 1.1.
10//! See <https://systemprompt.io> for licensing details.
11
12use chrono::Utc;
13use serde::{Deserialize, Serialize};
14use systemprompt_traits::validation::{
15    MetadataValidation, Validate, ValidationError, ValidationResult,
16};
17
18use crate::execution::ExecutionStep;
19
20pub mod agent_names {
21    pub const SYSTEM: &str = "system";
22}
23
24#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Hash)]
25#[serde(rename_all = "snake_case")]
26pub enum TaskType {
27    McpExecution,
28    AgentMessage,
29}
30
31#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
32pub struct TaskMetadata {
33    pub task_type: TaskType,
34    pub agent_name: String,
35    pub created_at: String,
36    #[serde(skip_serializing_if = "Option::is_none")]
37    pub updated_at: Option<String>,
38    #[serde(skip_serializing_if = "Option::is_none")]
39    pub started_at: Option<String>,
40    #[serde(skip_serializing_if = "Option::is_none")]
41    pub completed_at: Option<String>,
42    #[serde(skip_serializing_if = "Option::is_none")]
43    pub execution_time_ms: Option<i64>,
44    #[serde(skip_serializing_if = "Option::is_none")]
45    pub tool_name: Option<String>,
46    #[serde(skip_serializing_if = "Option::is_none")]
47    pub mcp_server_name: Option<String>,
48    #[serde(skip_serializing_if = "Option::is_none")]
49    pub input_tokens: Option<u32>,
50    #[serde(skip_serializing_if = "Option::is_none")]
51    pub output_tokens: Option<u32>,
52    #[serde(skip_serializing_if = "Option::is_none")]
53    pub model: Option<String>,
54    #[serde(rename = "executionSteps", skip_serializing_if = "Option::is_none")]
55    pub execution_steps: Option<Vec<ExecutionStep>>,
56    // `flatten` ignores `skip_serializing_if`; an empty map already flattens to
57    // no fields and deserialises back to an empty map, so the type round-trips.
58    #[serde(flatten, default)]
59    pub extensions: serde_json::Map<String, serde_json::Value>,
60}
61
62impl TaskMetadata {
63    pub fn new_mcp_execution(
64        agent_name: String,
65        tool_name: String,
66        mcp_server_name: String,
67    ) -> Self {
68        Self {
69            task_type: TaskType::McpExecution,
70            agent_name,
71            tool_name: Some(tool_name),
72            mcp_server_name: Some(mcp_server_name),
73            created_at: Utc::now().to_rfc3339(),
74            updated_at: None,
75            started_at: None,
76            completed_at: None,
77            execution_time_ms: None,
78            input_tokens: None,
79            output_tokens: None,
80            model: None,
81            execution_steps: None,
82            extensions: serde_json::Map::new(),
83        }
84    }
85
86    pub fn new_agent_message(agent_name: String) -> Self {
87        Self {
88            task_type: TaskType::AgentMessage,
89            agent_name,
90            tool_name: None,
91            mcp_server_name: None,
92            created_at: Utc::now().to_rfc3339(),
93            updated_at: None,
94            started_at: None,
95            completed_at: None,
96            execution_time_ms: None,
97            input_tokens: None,
98            output_tokens: None,
99            model: None,
100            execution_steps: None,
101            extensions: serde_json::Map::new(),
102        }
103    }
104
105    pub const fn with_token_usage(mut self, input_tokens: u32, output_tokens: u32) -> Self {
106        self.input_tokens = Some(input_tokens);
107        self.output_tokens = Some(output_tokens);
108        self
109    }
110
111    pub fn with_model(mut self, model: impl Into<String>) -> Self {
112        self.model = Some(model.into());
113        self
114    }
115
116    pub fn with_updated_at(mut self) -> Self {
117        self.updated_at = Some(Utc::now().to_rfc3339());
118        self
119    }
120
121    pub fn with_tool_name(mut self, tool_name: impl Into<String>) -> Self {
122        self.tool_name = Some(tool_name.into());
123        self
124    }
125
126    pub fn with_execution_steps(mut self, steps: Vec<ExecutionStep>) -> Self {
127        self.execution_steps = Some(steps);
128        self
129    }
130
131    pub fn with_extension(mut self, key: String, value: serde_json::Value) -> Self {
132        self.extensions.insert(key, value);
133        self
134    }
135
136    pub fn new_validated_agent_message(agent_name: String) -> ValidationResult<Self> {
137        if agent_name.is_empty() {
138            return Err(ValidationError::new(
139                "agent_name",
140                "Cannot create TaskMetadata: agent_name is empty",
141            )
142            .with_context(format!("agent_name={agent_name:?}")));
143        }
144
145        let metadata = Self::new_agent_message(agent_name);
146        metadata.validate()?;
147        Ok(metadata)
148    }
149
150    pub fn new_validated_mcp_execution(
151        agent_name: String,
152        tool_name: String,
153        mcp_server_name: String,
154    ) -> ValidationResult<Self> {
155        if agent_name.is_empty() {
156            return Err(ValidationError::new(
157                "agent_name",
158                "Cannot create TaskMetadata: agent_name is empty",
159            )
160            .with_context(format!("agent_name={agent_name:?}")));
161        }
162
163        if tool_name.is_empty() {
164            return Err(ValidationError::new(
165                "tool_name",
166                "Cannot create TaskMetadata: tool_name is empty for MCP execution",
167            )
168            .with_context(format!("tool_name={tool_name:?}")));
169        }
170
171        let metadata = Self::new_mcp_execution(agent_name, tool_name, mcp_server_name);
172        metadata.validate()?;
173        Ok(metadata)
174    }
175}
176
177impl Validate for TaskMetadata {
178    fn validate(&self) -> ValidationResult<()> {
179        self.validate_required_fields()?;
180        Ok(())
181    }
182}
183
184impl MetadataValidation for TaskMetadata {
185    fn required_string_fields(&self) -> Vec<(&'static str, &str)> {
186        vec![
187            ("agent_name", &self.agent_name),
188            ("created_at", &self.created_at),
189        ]
190    }
191}
systemprompt_models/a2a/task_metadata.rs

systemprompt_models/a2a/
task_metadata.rs
