1use crate::tools::ToolExecutionResult;
4use serde::{Deserialize, Serialize};
5use serde_json::{Value, json};
6
7pub const SESSION_SANDBOX_CAPABILITY_ID: &str = "session_sandbox";
9pub const SESSION_SANDBOX_SECRET_NAME: &str = "session_sandbox";
11pub const DEFAULT_SESSION_SANDBOX_IDLE_TIMEOUT_SECS: u64 = 180;
13
14#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
16pub struct SessionSandboxConfig {
17 pub provider: String,
19 #[serde(default = "default_true")]
21 pub auto_start: bool,
22 #[serde(default = "default_idle_timeout")]
24 pub idle_pause_after_seconds: u64,
25 #[serde(default = "default_true")]
27 pub idle_pause_enabled: bool,
28 #[serde(default = "default_provider_config")]
30 pub provider_config: Value,
31 #[serde(default)]
33 pub init: SessionSandboxInitConfig,
34}
35
36impl Default for SessionSandboxConfig {
37 fn default() -> Self {
38 Self {
39 provider: String::new(),
40 auto_start: true,
41 idle_pause_after_seconds: DEFAULT_SESSION_SANDBOX_IDLE_TIMEOUT_SECS,
42 idle_pause_enabled: true,
43 provider_config: default_provider_config(),
44 init: SessionSandboxInitConfig::default(),
45 }
46 }
47}
48
49#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq)]
51pub struct SessionSandboxInitConfig {
52 #[serde(default)]
53 pub commands: Vec<String>,
54}
55
56#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
58#[serde(rename_all = "snake_case")]
59pub enum SessionSandboxStatus {
60 Running,
61 Paused,
62 Lost,
64}
65
66#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq)]
68pub struct SessionSandboxInstance {
69 pub external_id: String,
71 #[serde(skip_serializing_if = "Option::is_none")]
73 pub display_name: Option<String>,
74 #[serde(skip_serializing_if = "Option::is_none")]
76 pub workspace_path: Option<String>,
77 #[serde(default)]
79 pub provider_state: Value,
80 #[serde(default)]
82 pub metadata: Value,
83}
84
85#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
87pub struct SessionSandboxState {
88 #[serde(skip)]
92 pub sandbox: Option<crate::sandbox_checkpoint::SandboxRef>,
93 pub provider: String,
94 pub status: SessionSandboxStatus,
95 pub instance: SessionSandboxInstance,
96 #[serde(skip_serializing_if = "Option::is_none")]
97 pub init_completed_at: Option<String>,
98 #[serde(skip_serializing_if = "Option::is_none")]
99 pub last_init_error: Option<String>,
100 pub created_at: String,
101 pub updated_at: String,
102}
103
104#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
106pub struct SessionSandboxExecRequest {
107 pub command: String,
108 #[serde(skip_serializing_if = "Option::is_none")]
109 pub cwd: Option<String>,
110 #[serde(skip_serializing_if = "Option::is_none")]
111 pub timeout_ms: Option<u64>,
112 #[serde(default = "default_output_mode")]
113 pub output_mode: String,
114}
115
116#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
118pub struct SessionSandboxExecResponse {
119 pub exit_code: i32,
120 pub stdout: String,
121 pub stderr: String,
122 pub success: bool,
123 pub truncated: bool,
124 pub total_lines: usize,
125 #[serde(skip_serializing_if = "Option::is_none")]
126 pub raw_output: Option<String>,
127 #[serde(skip_serializing_if = "Option::is_none")]
128 pub hint: Option<String>,
129}
130
131#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
133pub struct SessionSandboxReadFileResponse {
134 pub path: String,
135 pub content: String,
136 pub encoding: String,
137}
138
139#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
141pub struct SessionSandboxWriteFileResponse {
142 pub path: String,
143 pub bytes_written: usize,
144}
145
146#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
148pub struct SessionSandboxStatusResponse {
149 pub provider: String,
150 pub session_status: SessionSandboxStatus,
151 pub external_id: String,
152 #[serde(skip_serializing_if = "Option::is_none")]
153 pub display_name: Option<String>,
154 #[serde(skip_serializing_if = "Option::is_none")]
155 pub workspace_path: Option<String>,
156 #[serde(default)]
157 pub metadata: Value,
158}
159
160#[async_trait::async_trait]
163pub trait SessionSandboxContext: Send + Sync {
164 fn session_id(&self) -> crate::typed_id::SessionId;
165
166 fn clone_context(&self) -> std::sync::Arc<dyn SessionSandboxContext>;
168
169 async fn connection_token(&self, provider: &str)
170 -> Result<Option<String>, ToolExecutionResult>;
171
172 async fn resource_labels(&self) -> serde_json::Map<String, Value>;
174
175 async fn refresh_lease(&self, lease: SessionSandboxLease) -> Result<(), ToolExecutionResult>;
177
178 async fn release_lease(
179 &self,
180 provider: &str,
181 external_id: &str,
182 ) -> Result<(), ToolExecutionResult>;
183}
184
185#[derive(Debug, Clone)]
188pub struct SessionSandboxLease {
189 pub provider: String,
190 pub external_id: String,
191 pub display_name: Option<String>,
192 pub duration_seconds: u32,
193 pub metadata: Value,
194}
195
196#[async_trait::async_trait]
198pub trait SessionSandboxProvider: Send + Sync {
199 fn id(&self) -> &str;
200
201 async fn create(
202 &self,
203 context: &dyn SessionSandboxContext,
204 config: &SessionSandboxConfig,
205 ) -> Result<SessionSandboxInstance, ToolExecutionResult>;
206
207 async fn resume(
208 &self,
209 context: &dyn SessionSandboxContext,
210 config: &SessionSandboxConfig,
211 instance: &SessionSandboxInstance,
212 ) -> Result<SessionSandboxInstance, ToolExecutionResult>;
213
214 async fn pause(
215 &self,
216 context: &dyn SessionSandboxContext,
217 config: &SessionSandboxConfig,
218 instance: &SessionSandboxInstance,
219 ) -> Result<SessionSandboxInstance, ToolExecutionResult>;
220
221 async fn delete(
222 &self,
223 context: &dyn SessionSandboxContext,
224 config: &SessionSandboxConfig,
225 instance: &SessionSandboxInstance,
226 ) -> Result<(), ToolExecutionResult>;
227
228 async fn exec(
229 &self,
230 context: &dyn SessionSandboxContext,
231 config: &SessionSandboxConfig,
232 instance: &SessionSandboxInstance,
233 request: &SessionSandboxExecRequest,
234 ) -> Result<SessionSandboxExecResponse, ToolExecutionResult>;
235
236 async fn read_file(
237 &self,
238 context: &dyn SessionSandboxContext,
239 config: &SessionSandboxConfig,
240 instance: &SessionSandboxInstance,
241 path: &str,
242 ) -> Result<SessionSandboxReadFileResponse, ToolExecutionResult>;
243
244 async fn write_file(
245 &self,
246 context: &dyn SessionSandboxContext,
247 config: &SessionSandboxConfig,
248 instance: &SessionSandboxInstance,
249 path: &str,
250 content: &[u8],
251 ) -> Result<SessionSandboxWriteFileResponse, ToolExecutionResult>;
252
253 async fn checkpoint(
256 &self,
257 _context: &dyn SessionSandboxContext,
258 _config: &SessionSandboxConfig,
259 instance: &SessionSandboxInstance,
260 ) -> Result<SessionSandboxInstance, ToolExecutionResult> {
261 Ok(instance.clone())
262 }
263
264 async fn rewind_checkpoint(
273 &self,
274 _context: &dyn SessionSandboxContext,
275 _config: &SessionSandboxConfig,
276 instance: &SessionSandboxInstance,
277 _revision: Option<&str>,
278 ) -> Result<SessionSandboxInstance, ToolExecutionResult> {
279 Ok(instance.clone())
280 }
281
282 async fn status(
283 &self,
284 context: &dyn SessionSandboxContext,
285 config: &SessionSandboxConfig,
286 state: &SessionSandboxState,
287 ) -> Result<SessionSandboxStatusResponse, ToolExecutionResult>;
288}
289
290#[cfg(feature = "session-sandbox")]
292pub struct SessionSandboxProviderPlugin {
293 pub factory: fn() -> Box<dyn SessionSandboxProvider>,
294}
295
296#[cfg(feature = "session-sandbox")]
297inventory::collect!(SessionSandboxProviderPlugin);
298
299#[cfg(feature = "session-sandbox")]
301pub fn create_session_sandbox_provider(
302 provider_id: &str,
303) -> Option<Box<dyn SessionSandboxProvider>> {
304 inventory::iter::<SessionSandboxProviderPlugin>
305 .into_iter()
306 .map(|plugin| (plugin.factory)())
307 .find(|provider| provider.id() == provider_id)
308}
309
310fn default_true() -> bool {
311 true
312}
313fn default_idle_timeout() -> u64 {
314 DEFAULT_SESSION_SANDBOX_IDLE_TIMEOUT_SECS
315}
316fn default_provider_config() -> Value {
317 json!({})
318}
319fn default_output_mode() -> String {
320 "auto".to_string()
322}