nucel_agent_core/
executor.rs

1use std::path::Path;
2
3use async_trait::async_trait;
4
5use crate::error::Result;
6use crate::session::AgentSession;
7use crate::types::{CachePoint, ExecutorType, HookConfig, PermissionMode};
8
9/// Capability flags for a provider implementation.
10#[derive(Debug, Clone)]
11pub struct AgentCapabilities {
12    /// Can resume/fork from an existing session.
13    pub session_resume: bool,
14    /// Exposes token usage information.
15    pub token_usage: bool,
16    /// Supports MCP tool integration.
17    pub mcp_support: bool,
18    /// Can run autonomously (bash, file ops).
19    pub autonomous_mode: bool,
20    /// Supports structured output via JSON Schema.
21    pub structured_output: bool,
22    /// Supports event-level streaming via `query_stream()`.
23    pub streaming: bool,
24    /// Supports user-defined hooks (pre/post tool, on stop).
25    pub hooks: bool,
26    /// Supports Anthropic-style prompt cache breakpoints.
27    pub prompt_caching: bool,
28    /// Supports extended-thinking budget.
29    pub extended_thinking: bool,
30}
31
32impl Default for AgentCapabilities {
33    fn default() -> Self {
34        Self {
35            session_resume: false,
36            token_usage: false,
37            mcp_support: false,
38            autonomous_mode: false,
39            structured_output: false,
40            streaming: false,
41            hooks: false,
42            prompt_caching: false,
43            extended_thinking: false,
44        }
45    }
46}
47
48/// Runtime availability of the provider.
49#[derive(Debug, Clone)]
50pub struct AvailabilityStatus {
51    pub available: bool,
52    pub reason: Option<String>,
53}
54
55/// Configuration for spawning a new session.
56#[derive(Debug, Clone, Default)]
57pub struct SpawnConfig {
58    /// Model to use (e.g. "claude-opus-4-6", "gpt-5-codex").
59    pub model: Option<String>,
60    /// Maximum tokens for responses.
61    pub max_tokens: Option<u32>,
62    /// Budget limit in USD for this session.
63    pub budget_usd: Option<f64>,
64    /// Permission mode for file/command operations.
65    pub permission_mode: Option<PermissionMode>,
66    /// Extra environment variables for the subprocess.
67    pub env: Vec<(String, String)>,
68    /// System prompt override.
69    pub system_prompt: Option<String>,
70    /// Reasoning effort level (provider-specific).
71    pub reasoning: Option<String>,
72    /// Maximum autonomous turns before returning (0 or None = provider default).
73    pub max_turns: Option<u32>,
74    /// Hook handlers (Claude Code today; no-op on other providers).
75    pub hook_config: Option<HookConfig>,
76    /// Prompt-cache breakpoints (Claude Code today; no-op elsewhere).
77    pub cache_breakpoints: Vec<CachePoint>,
78    /// Extended-thinking budget in tokens (Claude Code's
79    /// `--thinking-budget-tokens`). Ignored by other providers.
80    pub thinking_budget: Option<u32>,
81}
82
83/// Configuration for the executor itself (not per-session).
84#[derive(Debug, Clone, Default)]
85pub struct ExecutorConfig {
86    /// API key for authentication.
87    pub api_key: Option<String>,
88    /// Base URL override (for OpenCode server, etc.).
89    pub base_url: Option<String>,
90    /// Working directory for CLI discovery.
91    pub working_dir: Option<String>,
92}
93
94/// Core trait — every provider implements this.
95///
96/// This is intentionally narrow: spawn, resume, capabilities, availability.
97/// Provider-specific features stay in the provider crate.
98#[async_trait]
99pub trait AgentExecutor: Send + Sync {
100    /// Which provider this executor implements.
101    fn executor_type(&self) -> ExecutorType;
102
103    /// Create a new session and send the first prompt.
104    async fn spawn(
105        &self,
106        working_dir: &Path,
107        prompt: &str,
108        config: &SpawnConfig,
109    ) -> Result<AgentSession>;
110
111    /// Resume an existing session with a follow-up prompt.
112    async fn resume(
113        &self,
114        working_dir: &Path,
115        session_id: &str,
116        prompt: &str,
117        config: &SpawnConfig,
118    ) -> Result<AgentSession>;
119
120    /// Static capability flags.
121    fn capabilities(&self) -> AgentCapabilities;
122
123    /// Check if the runtime dependency (CLI, server) is available.
124    fn availability(&self) -> AvailabilityStatus;
125}
nucel_agent_core/executor.rs

nucel_agent_core/
executor.rs
