everruns_core/
agent.rs

1// Agent domain types
2//
3// Design Decision: Dual-ID pattern (see specs/id-schema.md)
4// - public_id: AgentId (external, API-facing, client-supplied or auto-generated)
5// - internal_id: Uuid (internal PK, used for FK references, never exposed in API)
6//
7// These types represent the Agent entity and its status.
8// Used by both API and worker crates.
9
10use chrono::{DateTime, Utc};
11use serde::{Deserialize, Serialize};
12use uuid::Uuid;
13
14use crate::capability_types::AgentCapabilityConfig;
15use crate::events::TokenUsage;
16use crate::mcp_server::{ScopedMcpServers, scoped_mcp_servers_is_empty};
17use crate::network_access::NetworkAccessList;
18use crate::session_file::InitialFile;
19use crate::tool_types::ToolDefinition;
20use crate::typed_id::{AgentId, AgentVersionId, ModelId, PrincipalId};
21
22#[cfg(feature = "openapi")]
23use utoipa::ToSchema;
24
25/// Agent lifecycle status.
26/// - `active`: Agent is available for use
27/// - `archived`: Agent is hidden from listings and cannot be modified or assigned
28/// - `deleted`: Agent is a tombstone kept only for historical references
29#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
30#[cfg_attr(feature = "openapi", derive(ToSchema))]
31#[cfg_attr(feature = "openapi", schema(example = "active"))]
32#[serde(rename_all = "lowercase")]
33pub enum AgentStatus {
34    /// Agent is available for use.
35    Active,
36    /// Agent is hidden from listings and cannot be modified or assigned.
37    Archived,
38    /// Agent is deleted and should only survive as a tombstone for references.
39    Deleted,
40}
41
42/// Reason a version was created. Stored as lower_snake_case text.
43/// One of `auto`, `manual`, `patch`, `minor`, `major`, `import`, `rollback`, `fork`.
44#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
45#[cfg_attr(feature = "openapi", derive(ToSchema))]
46#[cfg_attr(feature = "openapi", schema(example = "manual"))]
47#[serde(rename_all = "snake_case")]
48pub enum AgentVersionChangeKind {
49    Auto,
50    Manual,
51    Patch,
52    Minor,
53    Major,
54    Import,
55    Rollback,
56    Fork,
57}
58
59impl std::fmt::Display for AgentVersionChangeKind {
60    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
61        match self {
62            AgentVersionChangeKind::Auto => write!(f, "auto"),
63            AgentVersionChangeKind::Manual => write!(f, "manual"),
64            AgentVersionChangeKind::Patch => write!(f, "patch"),
65            AgentVersionChangeKind::Minor => write!(f, "minor"),
66            AgentVersionChangeKind::Major => write!(f, "major"),
67            AgentVersionChangeKind::Import => write!(f, "import"),
68            AgentVersionChangeKind::Rollback => write!(f, "rollback"),
69            AgentVersionChangeKind::Fork => write!(f, "fork"),
70        }
71    }
72}
73
74impl From<&str> for AgentVersionChangeKind {
75    fn from(s: &str) -> Self {
76        match s {
77            "auto" => AgentVersionChangeKind::Auto,
78            "patch" => AgentVersionChangeKind::Patch,
79            "minor" => AgentVersionChangeKind::Minor,
80            "major" => AgentVersionChangeKind::Major,
81            "import" => AgentVersionChangeKind::Import,
82            "rollback" => AgentVersionChangeKind::Rollback,
83            "fork" => AgentVersionChangeKind::Fork,
84            _ => AgentVersionChangeKind::Manual,
85        }
86    }
87}
88
89/// Immutable snapshot of an Agent's authored and resolved runtime config.
90#[derive(Debug, Clone, Serialize, Deserialize)]
91#[cfg_attr(feature = "openapi", derive(ToSchema))]
92pub struct AgentVersion {
93    /// Prefixed public identifier. See [ID Schema](https://docs.everruns.com/advanced/id-schema/).
94    #[serde(rename = "id")]
95    #[cfg_attr(feature = "openapi", schema(value_type = String, example = "agentver_01933b5a000070008000000000000001"))]
96    pub public_id: AgentVersionId,
97    /// Internal database UUID. Not part of the public identifier surface; skipped during serialization.
98    #[serde(skip, default = "uuid::Uuid::nil")]
99    pub internal_id: uuid::Uuid,
100    /// Owning agent's prefixed public identifier.
101    #[cfg_attr(feature = "openapi", schema(value_type = String, example = "agent_01933b5a000070008000000000000001"))]
102    pub agent_id: AgentId,
103    /// Monotonic per-agent version sequence number (1, 2, 3, ...). Increments on every snapshot.
104    #[cfg_attr(feature = "openapi", schema(example = 7))]
105    pub version_number: i32,
106    /// Semantic version major component.
107    #[cfg_attr(feature = "openapi", schema(example = 1))]
108    pub semver_major: i32,
109    /// Semantic version minor component.
110    #[cfg_attr(feature = "openapi", schema(example = 4))]
111    pub semver_minor: i32,
112    /// Semantic version patch component.
113    #[cfg_attr(feature = "openapi", schema(example = 2))]
114    pub semver_patch: i32,
115    /// Combined semver string for display (e.g. `1.4.2`).
116    #[cfg_attr(feature = "openapi", schema(example = "1.4.2"))]
117    pub version: String,
118    /// Whether this version was explicitly published by a user. Published versions are user-controlled semver releases; unpublished rows are automatic draft snapshots kept for audit and rollback.
119    #[cfg_attr(feature = "openapi", schema(example = true))]
120    pub is_published: bool,
121    /// Version this one was forked or branched from, if any.
122    #[serde(skip_serializing_if = "Option::is_none")]
123    #[cfg_attr(feature = "openapi", schema(value_type = Option<String>))]
124    pub parent_version_id: Option<AgentVersionId>,
125    /// When this version is a copy of another version (e.g. a manual rollback), the original source. `None` for ordinary snapshots.
126    #[serde(skip_serializing_if = "Option::is_none")]
127    #[cfg_attr(feature = "openapi", schema(value_type = Option<String>))]
128    pub source_version_id: Option<AgentVersionId>,
129    /// Identity of the principal (user or agent identity) that created this version. `None` for system-generated snapshots.
130    #[serde(skip_serializing_if = "Option::is_none")]
131    #[cfg_attr(feature = "openapi", schema(value_type = Option<String>))]
132    pub created_by_principal_id: Option<PrincipalId>,
133    /// Classification of why this version was created (manual publish, automatic draft, rollback, fork, etc.).
134    pub change_kind: AgentVersionChangeKind,
135    /// Human-readable summary of changes in this version (release notes). `None` if not provided.
136    #[serde(skip_serializing_if = "Option::is_none")]
137    #[cfg_attr(
138        feature = "openapi",
139        schema(
140            example = "Switched default model to claude-sonnet-4-6; added refund-runbook capability."
141        )
142    )]
143    pub summary: Option<String>,
144    /// Stable hash of `resolved_config` used to deduplicate adjacent identical snapshots.
145    #[cfg_attr(
146        feature = "openapi",
147        schema(
148            example = "blake3:9f1e2a4c3d5b6e8a0b2c4d6e8f0a1b3c5d7e9f0a1b2c4d6e8f0a1b2c4d6e8f0a"
149        )
150    )]
151    pub config_hash: String,
152    /// User-authored agent configuration JSON, exactly as submitted. Capabilities, MCP refs, model selection live here.
153    #[cfg_attr(feature = "openapi", schema(value_type = Object))]
154    pub authored_config: serde_json::Value,
155    /// Resolved configuration after applying harness, capability, and platform layers. This is what the runtime executes against.
156    #[cfg_attr(feature = "openapi", schema(value_type = Object))]
157    pub resolved_config: serde_json::Value,
158    /// Timestamp when this version was created (RFC 3339).
159    #[cfg_attr(feature = "openapi", schema(example = "2026-04-20T14:22:00Z"))]
160    pub created_at: DateTime<Utc>,
161}
162
163impl std::fmt::Display for AgentStatus {
164    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
165        match self {
166            AgentStatus::Active => write!(f, "active"),
167            AgentStatus::Archived => write!(f, "archived"),
168            AgentStatus::Deleted => write!(f, "deleted"),
169        }
170    }
171}
172
173impl From<&str> for AgentStatus {
174    fn from(s: &str) -> Self {
175        match s {
176            "archived" => AgentStatus::Archived,
177            "deleted" => AgentStatus::Deleted,
178            _ => AgentStatus::Active,
179        }
180    }
181}
182
183/// Agent configuration for agentic loop.
184/// An agent defines the behavior and capabilities of an AI assistant.
185#[derive(Debug, Clone, Serialize, Deserialize)]
186#[cfg_attr(feature = "openapi", derive(ToSchema))]
187pub struct Agent {
188    /// External identifier (agent_<32-hex>). Shown as "id" in API.
189    /// Client-supplied or auto-generated.
190    #[serde(rename = "id")]
191    #[cfg_attr(feature = "openapi", schema(value_type = String, example = "agent_01933b5a000070008000000000000001"))]
192    pub public_id: AgentId,
193    /// Internal UUID primary key. Used for FK references. Never exposed in API.
194    #[serde(skip, default = "Uuid::nil")]
195    pub internal_id: Uuid,
196    /// Name, unique per org (e.g. "customer-support").
197    #[cfg_attr(feature = "openapi", schema(example = "customer-support"))]
198    pub name: String,
199    /// Human-readable display name shown in UI (e.g. "Customer Support Agent").
200    /// Falls back to `name` when absent.
201    #[serde(default, skip_serializing_if = "Option::is_none")]
202    #[cfg_attr(feature = "openapi", schema(example = "Customer Support Agent"))]
203    pub display_name: Option<String>,
204    /// Human-readable description of what the agent does.
205    #[serde(skip_serializing_if = "Option::is_none")]
206    #[cfg_attr(
207        feature = "openapi",
208        schema(example = "Handles refund and shipping questions; escalates billing disputes.")
209    )]
210    pub description: Option<String>,
211    /// System prompt that defines the agent's behavior.
212    /// Sent as the first message in every conversation.
213    #[cfg_attr(
214        feature = "openapi",
215        schema(
216            example = "You are a friendly customer support agent for Acme Corp. Verify orders before issuing refunds. Escalate any billing disputes to a human."
217        )
218    )]
219    pub system_prompt: String,
220    /// Default LLM model ID for this agent.
221    /// Can be overridden at the session level.
222    #[serde(skip_serializing_if = "Option::is_none")]
223    #[cfg_attr(feature = "openapi", schema(value_type = Option<String>, example = "model_01933b5a00007000800000000000001"))]
224    pub default_model_id: Option<ModelId>,
225    /// Default immutable version used by deployments that choose the default policy.
226    #[serde(skip_serializing_if = "Option::is_none")]
227    #[cfg_attr(feature = "openapi", schema(value_type = Option<String>, example = "agentver_01933b5a00007000800000000000001"))]
228    pub default_version_id: Option<AgentVersionId>,
229    /// Source agent for a forked agent.
230    #[serde(skip_serializing_if = "Option::is_none")]
231    #[cfg_attr(feature = "openapi", schema(value_type = Option<String>, example = "agent_01933b5a00007000800000000000001"))]
232    pub forked_from_agent_id: Option<AgentId>,
233    /// Source version for a forked agent.
234    #[serde(skip_serializing_if = "Option::is_none")]
235    #[cfg_attr(feature = "openapi", schema(value_type = Option<String>, example = "agentver_01933b5a00007000800000000000001"))]
236    pub forked_from_version_id: Option<AgentVersionId>,
237    /// Root agent lineage identifier for grouping fork families.
238    #[serde(skip_serializing_if = "Option::is_none")]
239    #[cfg_attr(feature = "openapi", schema(value_type = Option<String>, example = "agent_01933b5a00007000800000000000001"))]
240    pub root_agent_id: Option<AgentId>,
241    /// Tags for organizing and filtering agents.
242    #[serde(default)]
243    #[cfg_attr(feature = "openapi", schema(example = json!(["support", "production"])))]
244    pub tags: Vec<String>,
245    /// Capabilities enabled for this agent with per-agent configuration.
246    /// Capabilities add tools and system prompt modifications.
247    #[serde(default)]
248    pub capabilities: Vec<AgentCapabilityConfig>,
249    /// Starter files copied into each new session for this agent.
250    #[serde(default, skip_serializing_if = "Vec::is_empty")]
251    pub initial_files: Vec<InitialFile>,
252    /// Network access list controlling which hosts/URLs agent sessions can reach.
253    /// Merged with harness and session layers (allowed: intersect, blocked: union).
254    #[serde(default, skip_serializing_if = "Option::is_none")]
255    pub network_access: Option<NetworkAccessList>,
256    /// Maximum number of LLM iterations per turn for this agent.
257    #[serde(default, skip_serializing_if = "Option::is_none")]
258    #[cfg_attr(feature = "openapi", schema(example = 50))]
259    pub max_iterations: Option<usize>,
260    /// Request-level parallel tool calling preference (EVE-598).
261    ///
262    /// `None` (default) preserves provider defaults. `Some(true)` signals the
263    /// provider that parallel tool calls are wanted; `Some(false)` requests at
264    /// most one tool call per turn and forces serial execution. Merged across
265    /// harness/agent/session layers (overlay wins).
266    #[serde(default, skip_serializing_if = "Option::is_none")]
267    #[cfg_attr(feature = "openapi", schema(example = true))]
268    pub parallel_tool_calls: Option<bool>,
269    /// Client-side tools registered for this agent.
270    /// These tools are executed by the client, not the server.
271    #[serde(default, skip_serializing_if = "Vec::is_empty")]
272    pub tools: Vec<ToolDefinition>,
273    /// Remote MCP servers scoped to this agent and inherited by its sessions.
274    #[serde(
275        default,
276        rename = "mcpServers",
277        alias = "mcp_servers",
278        skip_serializing_if = "scoped_mcp_servers_is_empty"
279    )]
280    pub mcp_servers: ScopedMcpServers,
281    /// Current lifecycle status of the agent.
282    pub status: AgentStatus,
283    /// Timestamp when the agent was created.
284    #[cfg_attr(feature = "openapi", schema(example = "2026-04-01T10:00:00Z"))]
285    pub created_at: DateTime<Utc>,
286    /// Timestamp when the agent was last updated.
287    #[cfg_attr(feature = "openapi", schema(example = "2026-05-20T14:00:00Z"))]
288    pub updated_at: DateTime<Utc>,
289    /// Timestamp when the agent was archived.
290    #[serde(skip_serializing_if = "Option::is_none")]
291    #[cfg_attr(feature = "openapi", schema(example = "2026-05-26T00:00:00Z"))]
292    pub archived_at: Option<DateTime<Utc>>,
293    /// Timestamp when the agent was deleted.
294    #[serde(skip_serializing_if = "Option::is_none")]
295    #[cfg_attr(feature = "openapi", schema(example = "2026-05-26T00:00:00Z"))]
296    pub deleted_at: Option<DateTime<Utc>>,
297    /// Cumulative token usage across all sessions for this agent.
298    #[serde(skip_serializing_if = "Option::is_none")]
299    pub usage: Option<TokenUsage>,
300}
301
302/// Maximum length for an addressable name (agent, harness, etc.).
303pub const MAX_ADDRESSABLE_NAME_LEN: usize = 64;
304
305/// Validate an addressable name: `[a-z0-9]([a-z0-9-]*[a-z0-9])?`.
306/// Max 64 chars, no consecutive hyphens, no leading/trailing hyphens.
307/// Returns `Ok(())` or a human-readable error message.
308pub fn validate_addressable_name(name: &str) -> Result<(), String> {
309    if name.is_empty() {
310        return Err("name must not be empty".to_string());
311    }
312    if name.len() > MAX_ADDRESSABLE_NAME_LEN {
313        return Err(format!(
314            "name must be at most {MAX_ADDRESSABLE_NAME_LEN} characters"
315        ));
316    }
317    if !name
318        .bytes()
319        .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'-')
320    {
321        return Err("name must contain only lowercase letters, digits, and hyphens".to_string());
322    }
323    if name.starts_with('-') || name.ends_with('-') {
324        return Err("name must not start or end with a hyphen".to_string());
325    }
326    if name.contains("--") {
327        return Err("name must not contain consecutive hyphens".to_string());
328    }
329    Ok(())
330}
331
332/// Generate a new agent public_id using UUIDv7.
333pub fn generate_agent_public_id() -> AgentId {
334    AgentId::new()
335}
336
337/// Validate an agent public_id string.
338/// Must match format: agent_<32-lowercase-hex-chars>
339pub fn validate_agent_public_id(s: &str) -> bool {
340    s.parse::<AgentId>().is_ok()
341}
342
343#[cfg(test)]
344mod tests {
345    use super::*;
346
347    #[test]
348    fn test_generate_agent_public_id() {
349        let id = generate_agent_public_id();
350        let s = id.to_string();
351        assert!(s.starts_with("agent_"));
352        assert_eq!(s.len(), 38); // "agent_" (6) + 32 hex chars
353        assert!(validate_agent_public_id(&s));
354    }
355
356    #[test]
357    fn test_validate_agent_public_id() {
358        assert!(validate_agent_public_id(
359            "agent_01933b5a000070008000000000000001"
360        ));
361        assert!(validate_agent_public_id(
362            "agent_4ab3e8452f1442e9865e11d2032a579c"
363        ));
364
365        // Invalid cases
366        assert!(!validate_agent_public_id(""));
367        assert!(!validate_agent_public_id("agent_"));
368        assert!(!validate_agent_public_id(
369            "session_01933b5a000070008000000000000001"
370        ));
371        assert!(!validate_agent_public_id(
372            "agent_4AB3E8452F1442E9865E11D2032A579C"
373        )); // uppercase
374        assert!(!validate_agent_public_id("agent_short"));
375        assert!(!validate_agent_public_id("my-custom-agent"));
376    }
377
378    #[test]
379    fn test_validate_addressable_name_valid() {
380        assert!(validate_addressable_name("my-agent").is_ok());
381        assert!(validate_addressable_name("agent1").is_ok());
382        assert!(validate_addressable_name("a").is_ok());
383        assert!(validate_addressable_name("customer-support").is_ok());
384        assert!(validate_addressable_name("a-b-c").is_ok());
385    }
386
387    #[test]
388    fn test_validate_addressable_name_invalid() {
389        assert!(validate_addressable_name("").is_err());
390        assert!(validate_addressable_name("-leading").is_err());
391        assert!(validate_addressable_name("trailing-").is_err());
392        assert!(validate_addressable_name("bad--double").is_err());
393        assert!(validate_addressable_name("UPPERCASE").is_err());
394        assert!(validate_addressable_name("has space").is_err());
395        assert!(validate_addressable_name("Customer Support Agent").is_err());
396        let long = "a".repeat(65);
397        assert!(validate_addressable_name(&long).is_err());
398    }
399
400    #[test]
401    fn test_agent_serde_public_id_as_id() {
402        let agent = Agent {
403            public_id: "agent_01933b5a000070008000000000000001".parse().unwrap(),
404            internal_id: Uuid::nil(),
405            name: "test".to_string(),
406            display_name: Some("Test".to_string()),
407            description: None,
408            system_prompt: "test".to_string(),
409            default_model_id: None,
410            default_version_id: None,
411            forked_from_agent_id: None,
412            forked_from_version_id: None,
413            root_agent_id: None,
414            tags: vec![],
415            capabilities: vec![],
416            initial_files: vec![],
417            network_access: None,
418            max_iterations: None,
419            parallel_tool_calls: None,
420            tools: vec![],
421            mcp_servers: ScopedMcpServers::default(),
422            status: AgentStatus::Active,
423            created_at: Utc::now(),
424            updated_at: Utc::now(),
425            archived_at: None,
426            deleted_at: None,
427            usage: None,
428        };
429
430        let json = serde_json::to_value(&agent).unwrap();
431        // public_id should serialize as "id"
432        assert_eq!(json["id"], "agent_01933b5a000070008000000000000001");
433        // internal_id should be skipped
434        assert!(json.get("internal_id").is_none());
435    }
436
437    #[test]
438    fn test_agent_deserialize_from_api_json() {
439        let json = serde_json::json!({
440            "id": "agent_01933b5a000070008000000000000001",
441            "name": "test",
442            "display_name": "Test",
443            "system_prompt": "test",
444            "status": "active",
445            "tags": [],
446            "created_at": "2024-01-01T00:00:00Z",
447            "updated_at": "2024-01-01T00:00:00Z"
448        });
449
450        let agent: Agent = serde_json::from_value(json).unwrap();
451        assert_eq!(
452            agent.public_id.to_string(),
453            "agent_01933b5a000070008000000000000001"
454        );
455        // internal_id defaults to nil when not present in JSON
456        assert_eq!(agent.internal_id, Uuid::nil());
457    }
458}
everruns_core/agent.rs

everruns_core/
agent.rs
