cli_agents/
types.rs

1use serde::{Deserialize, Serialize};
2use std::collections::HashMap;
3
4/// Supported CLI agents.
5#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
6#[serde(rename_all = "lowercase")]
7#[non_exhaustive]
8pub enum CliName {
9    Claude,
10    Codex,
11    Gemini,
12}
13
14impl std::fmt::Display for CliName {
15    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
16        match self {
17            Self::Claude => write!(f, "claude"),
18            Self::Codex => write!(f, "codex"),
19            Self::Gemini => write!(f, "gemini"),
20        }
21    }
22}
23
24/// MCP server configuration.
25#[derive(Debug, Clone, Default, Serialize, Deserialize)]
26#[serde(rename_all = "camelCase")]
27pub struct McpServer {
28    // ── stdio transport ──
29    pub command: Option<String>,
30    pub args: Option<Vec<String>>,
31    pub env: Option<HashMap<String, String>>,
32    pub cwd: Option<String>,
33
34    // ── HTTP/SSE transport ──
35    pub url: Option<String>,
36    #[serde(rename = "type")]
37    pub transport_type: Option<McpTransport>,
38    pub headers: Option<HashMap<String, String>>,
39
40    // ── Tool filtering ──
41    pub include_tools: Option<Vec<String>>,
42    pub exclude_tools: Option<Vec<String>>,
43
44    // ── Timeouts ──
45    pub timeout: Option<u64>,
46}
47
48#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
49#[serde(rename_all = "lowercase")]
50pub enum McpTransport {
51    Stdio,
52    Sse,
53    Http,
54}
55
56// ── Provider-specific options ──
57
58#[derive(Debug, Clone, Default, Serialize, Deserialize)]
59#[serde(rename_all = "camelCase")]
60pub struct ClaudeOptions {
61    pub allowed_tools: Option<String>,
62    pub disallowed_tools: Option<String>,
63    pub tools: Option<String>,
64    pub append_system_prompt: Option<String>,
65    pub max_turns: Option<u32>,
66    pub max_budget_usd: Option<f64>,
67    pub max_thinking_tokens: Option<u32>,
68    pub continue_session: Option<bool>,
69    pub include_partial_messages: Option<bool>,
70    pub effort: Option<String>,
71    pub agents: Option<serde_json::Value>,
72}
73
74#[derive(Debug, Clone, Default, Serialize, Deserialize)]
75#[serde(rename_all = "camelCase")]
76pub struct CodexOptions {
77    pub approval_policy: Option<String>,
78    pub sandbox_mode: Option<String>,
79    pub additional_directories: Option<Vec<String>>,
80    pub images: Option<Vec<String>>,
81    pub output_schema: Option<String>,
82}
83
84#[derive(Debug, Clone, Default, Serialize, Deserialize)]
85#[serde(rename_all = "camelCase")]
86pub struct GeminiOptions {
87    pub approval_mode: Option<String>,
88    pub sandbox: Option<bool>,
89    pub extra_args: Option<Vec<String>>,
90}
91
92#[derive(Debug, Clone, Default, Serialize, Deserialize)]
93pub struct ProviderOptions {
94    pub claude: Option<ClaudeOptions>,
95    pub codex: Option<CodexOptions>,
96    pub gemini: Option<GeminiOptions>,
97}
98
99/// Options passed to [`run()`](crate::run).
100#[derive(Debug, Clone, Default, Serialize, Deserialize)]
101#[serde(rename_all = "camelCase")]
102pub struct RunOptions {
103    /// Which CLI to use. If `None`, auto-discovers the first available.
104    pub cli: Option<CliName>,
105
106    /// The task/prompt to send to the agent.
107    pub task: String,
108
109    /// System prompt (where supported).
110    pub system_prompt: Option<String>,
111
112    /// Path to a system prompt file (alternative to inline `system_prompt`).
113    pub system_prompt_file: Option<String>,
114
115    /// MCP servers to connect.
116    pub mcp_servers: Option<HashMap<String, McpServer>>,
117
118    /// Working directory for the CLI process.
119    pub cwd: Option<String>,
120
121    /// Model name (e.g. "sonnet", "opus", "o3").
122    pub model: Option<String>,
123
124    /// Idle timeout in milliseconds. Default: 300_000 (5 minutes).
125    pub idle_timeout_ms: Option<u64>,
126
127    /// Total timeout in milliseconds. No default.
128    pub total_timeout_ms: Option<u64>,
129
130    /// Max consecutive tool failures before aborting. Default: 3.
131    pub max_consecutive_tool_failures: Option<u32>,
132
133    /// Extra environment variables for the CLI process.
134    pub env: Option<HashMap<String, String>>,
135
136    /// Explicit path to the CLI executable (skips discovery).
137    pub executable_path: Option<String>,
138
139    /// Session ID to resume a previous conversation.
140    pub resume_session_id: Option<String>,
141
142    /// Maximum bytes to buffer from CLI stdout before aborting.
143    ///
144    /// Prevents OOM if the CLI produces unexpectedly large output.
145    /// Defaults to 10 MB when `None`.
146    pub max_output_bytes: Option<usize>,
147
148    /// Skip permission prompts and run in fully autonomous mode.
149    ///
150    /// When `true`, passes provider-specific flags to bypass interactive approval
151    /// (e.g. `--dangerously-skip-permissions` for Claude). **Use with caution** —
152    /// the agent will be able to execute tools without human confirmation.
153    ///
154    /// Defaults to `false`.
155    #[serde(default)]
156    pub skip_permissions: bool,
157
158    /// Provider-specific options.
159    pub providers: Option<ProviderOptions>,
160}
161
162/// Result from a completed run.
163#[derive(Debug, Clone, Default, Serialize, Deserialize)]
164#[serde(rename_all = "camelCase")]
165#[non_exhaustive]
166pub struct RunResult {
167    pub success: bool,
168    pub text: Option<String>,
169    pub exit_code: Option<i32>,
170    pub stats: Option<RunStats>,
171    pub session_id: Option<String>,
172    pub stderr: Option<String>,
173    pub cost_usd: Option<f64>,
174}
175
176#[derive(Debug, Clone, Default, Serialize, Deserialize)]
177#[serde(rename_all = "camelCase")]
178#[non_exhaustive]
179pub struct RunStats {
180    pub input_tokens: Option<u64>,
181    pub output_tokens: Option<u64>,
182    pub total_tokens: Option<u64>,
183    pub cached_tokens: Option<u64>,
184    pub duration_ms: Option<u64>,
185    pub tool_calls: Option<u32>,
186}
cli_agents/types.rs

cli_agents/
types.rs
