unified_agent_sdk/
types.rs

1//! Core public types shared across unified executors, sessions, and events.
2//!
3//! These types are intentionally provider-agnostic. They model concepts that stay
4//! stable even when the backing agent changes from Codex to Claude Code or future
5//! providers.
6
7use serde::{Deserialize, Serialize};
8
9/// Provider identifier used throughout the unified SDK.
10///
11/// This enum is used in profile resolution, session metadata, and executor
12/// selection logic.
13#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
14pub enum ExecutorType {
15    /// Anthropic Claude Code executor backend.
16    ClaudeCode,
17    /// OpenAI Codex executor backend.
18    Codex,
19}
20
21/// Logical role associated with a normalized message event.
22#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
23pub enum Role {
24    /// End-user message.
25    User,
26    /// Assistant-generated message.
27    Assistant,
28    /// System-level instruction or status message.
29    System,
30}
31
32/// High-level lifecycle state for a tool call after normalization.
33#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
34pub enum ToolStatus {
35    /// Tool call has started.
36    Started,
37    /// Tool call is in progress.
38    Running,
39    /// Tool call completed successfully.
40    Completed,
41    /// Tool call failed.
42    Failed,
43}
44
45/// Provider-agnostic permission behavior requested by the caller.
46///
47/// Each executor maps this enum to its provider-specific approval or sandboxing
48/// model. Unsupported combinations are surfaced as configuration errors.
49#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
50pub enum PermissionPolicy {
51    /// Automatically allow tool execution without prompts.
52    Bypass,
53    /// Ask for approval when needed.
54    Prompt,
55    /// Deny operations that require elevated trust.
56    Deny,
57}
58
59/// Source used to determine the context-window capacity reported in [`ContextUsage`].
60#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
61pub enum ContextUsageSource {
62    /// Window capacity reported directly by the underlying SDK/CLI stream.
63    ProviderReported,
64    /// Window capacity supplied through runtime SDK configuration.
65    ConfigOverride,
66    /// Window capacity is unknown.
67    Unknown,
68}
69
70/// Unified context-window usage snapshot emitted through [`crate::event::AgentEvent::ContextUsageUpdated`].
71///
72/// Use this value when you need consistent usage telemetry across different
73/// providers. If a provider does not report a context limit directly, the SDK may
74/// derive it from `SpawnConfig::context_window_override_tokens`.
75///
76/// # Examples
77///
78/// ```rust
79/// use unified_agent_sdk::{ContextUsage, ContextUsageSource};
80///
81/// let usage = ContextUsage {
82///     used_tokens: 1200,
83///     window_tokens: Some(8000),
84///     remaining_tokens: Some(6800),
85///     utilization: Some(0.15),
86///     source: ContextUsageSource::ProviderReported,
87/// };
88///
89/// assert_eq!(usage.remaining_tokens, Some(6800));
90/// ```
91#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
92pub struct ContextUsage {
93    /// Tokens currently consumed in the active context snapshot.
94    pub used_tokens: u32,
95    /// Context window capacity when known.
96    pub window_tokens: Option<u32>,
97    /// Remaining tokens in the context window when capacity is known.
98    pub remaining_tokens: Option<u32>,
99    /// Usage ratio in range `[0.0, 1.0]` when capacity is known.
100    pub utilization: Option<f32>,
101    /// Provenance of the reported capacity information.
102    pub source: ContextUsageSource,
103}
104
105/// Exit summary for a spawned or resumed unified session.
106///
107/// This is intentionally simpler than provider-native process state. It captures
108/// the information most callers need for orchestration and persistence.
109#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
110pub struct ExitStatus {
111    /// Numeric exit code if available.
112    pub code: Option<i32>,
113    /// Whether the process reported success.
114    pub success: bool,
115}
unified_agent_sdk/types.rs

unified_agent_sdk/
types.rs
