agentkernel_sdk/
types.rs

1use serde::{Deserialize, Serialize};
2
3/// Security profile for sandbox execution.
4#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
5#[serde(rename_all = "lowercase")]
6pub enum SecurityProfile {
7    Permissive,
8    Moderate,
9    Restrictive,
10}
11
12/// Options for running a command.
13#[derive(Debug, Default, Serialize)]
14pub struct RunOptions {
15    #[serde(skip_serializing_if = "Option::is_none")]
16    pub image: Option<String>,
17    #[serde(skip_serializing_if = "Option::is_none")]
18    pub profile: Option<SecurityProfile>,
19    #[serde(skip_serializing_if = "Option::is_none")]
20    pub fast: Option<bool>,
21}
22
23/// Output from a command execution.
24#[derive(Debug, Deserialize)]
25pub struct RunOutput {
26    pub output: String,
27}
28
29/// Information about a sandbox.
30#[derive(Debug, Deserialize)]
31pub struct SandboxInfo {
32    pub name: String,
33    pub status: String,
34    pub backend: String,
35    pub image: Option<String>,
36    pub vcpus: Option<u32>,
37    pub memory_mb: Option<u64>,
38    pub created_at: Option<String>,
39}
40
41/// SSE stream event.
42#[derive(Debug)]
43pub struct StreamEvent {
44    pub event_type: String,
45    pub data: serde_json::Value,
46}
47
48/// API response wrapper (internal).
49#[derive(Debug, Deserialize)]
50pub(crate) struct ApiResponse<T> {
51    pub success: bool,
52    pub data: Option<T>,
53    pub error: Option<String>,
54}
55
56/// Run request body (internal).
57#[derive(Serialize)]
58pub(crate) struct RunRequest {
59    pub command: Vec<String>,
60    #[serde(skip_serializing_if = "Option::is_none")]
61    pub image: Option<String>,
62    #[serde(skip_serializing_if = "Option::is_none")]
63    pub profile: Option<SecurityProfile>,
64    pub fast: bool,
65}
66
67/// Options for creating a sandbox with a git source.
68#[derive(Debug, Default, Serialize)]
69pub struct CreateSandboxOptions {
70    /// Docker image to use.
71    #[serde(skip_serializing_if = "Option::is_none")]
72    pub image: Option<String>,
73    #[serde(skip_serializing_if = "Option::is_none")]
74    pub vcpus: Option<u32>,
75    #[serde(skip_serializing_if = "Option::is_none")]
76    pub memory_mb: Option<u64>,
77    #[serde(skip_serializing_if = "Option::is_none")]
78    pub profile: Option<SecurityProfile>,
79    /// Git repository URL to clone into the sandbox.
80    #[serde(skip_serializing_if = "Option::is_none")]
81    pub source_url: Option<String>,
82    /// Git ref to checkout after cloning.
83    #[serde(skip_serializing_if = "Option::is_none")]
84    pub source_ref: Option<String>,
85    /// Volume mounts (slug:/path or slug:/path:ro). Create volumes via CLI first.
86    #[serde(skip_serializing_if = "Vec::is_empty")]
87    #[serde(default)]
88    pub volumes: Vec<String>,
89}
90
91/// Create sandbox request body (internal).
92#[derive(Serialize)]
93pub(crate) struct CreateRequest {
94    pub name: String,
95    #[serde(skip_serializing_if = "Option::is_none")]
96    pub image: Option<String>,
97    #[serde(skip_serializing_if = "Option::is_none")]
98    pub vcpus: Option<u32>,
99    #[serde(skip_serializing_if = "Option::is_none")]
100    pub memory_mb: Option<u64>,
101    #[serde(skip_serializing_if = "Option::is_none")]
102    pub profile: Option<SecurityProfile>,
103    #[serde(skip_serializing_if = "Option::is_none")]
104    pub source_url: Option<String>,
105    #[serde(skip_serializing_if = "Option::is_none")]
106    pub source_ref: Option<String>,
107    #[serde(skip_serializing_if = "Vec::is_empty")]
108    #[serde(default)]
109    pub volumes: Vec<String>,
110}
111
112/// Options for executing a command in a sandbox.
113#[derive(Debug, Default, Serialize)]
114pub struct ExecOptions {
115    /// Environment variables (`KEY=VALUE`).
116    #[serde(skip_serializing_if = "Vec::is_empty")]
117    pub env: Vec<String>,
118    /// Working directory inside the container.
119    #[serde(skip_serializing_if = "Option::is_none")]
120    pub workdir: Option<String>,
121    /// Run as root (maps to `--sudo` on CLI).
122    #[serde(skip_serializing_if = "Option::is_none")]
123    pub sudo: Option<bool>,
124}
125
126/// Exec request body (internal).
127#[derive(Serialize)]
128pub(crate) struct ExecRequest {
129    pub command: Vec<String>,
130    #[serde(skip_serializing_if = "Vec::is_empty")]
131    pub env: Vec<String>,
132    #[serde(skip_serializing_if = "Option::is_none")]
133    pub workdir: Option<String>,
134    #[serde(skip_serializing_if = "Option::is_none")]
135    pub sudo: Option<bool>,
136}
137
138/// File write request body (internal).
139#[derive(Serialize)]
140pub(crate) struct FileWriteRequest {
141    pub content: String,
142    #[serde(skip_serializing_if = "Option::is_none")]
143    pub encoding: Option<String>,
144}
145
146/// Response from reading a file.
147#[derive(Debug, Deserialize)]
148pub struct FileReadResponse {
149    pub content: String,
150    pub encoding: String,
151    pub size: usize,
152}
153
154/// Batch run request body (internal).
155#[derive(Serialize)]
156pub(crate) struct BatchRunRequest {
157    pub commands: Vec<BatchCommand>,
158}
159
160/// A command for batch execution.
161#[derive(Debug, Serialize)]
162pub struct BatchCommand {
163    pub command: Vec<String>,
164}
165
166/// Result of a single batch command.
167#[derive(Debug, Deserialize)]
168pub struct BatchResult {
169    pub output: Option<String>,
170    pub error: Option<String>,
171}
172
173/// Response from batch execution.
174#[derive(Debug, Deserialize)]
175pub struct BatchRunResponse {
176    pub results: Vec<BatchResult>,
177}
178
179/// Batch file write request body (internal).
180#[derive(Serialize)]
181pub(crate) struct BatchFileWriteRequest {
182    pub files: std::collections::HashMap<String, String>,
183}
184
185/// Result of a batch file write.
186#[derive(Debug, Deserialize)]
187pub struct BatchFileWriteResponse {
188    pub written: usize,
189}
190
191/// Response from extending a sandbox's TTL.
192#[derive(Debug, Deserialize)]
193pub struct ExtendTtlResponse {
194    pub expires_at: Option<String>,
195}
196
197/// Request body for extending TTL (internal).
198#[derive(Serialize)]
199pub(crate) struct ExtendTtlRequest {
200    pub by: String,
201}
202
203/// Metadata for a sandbox snapshot.
204#[derive(Debug, Deserialize)]
205pub struct SnapshotMeta {
206    pub name: String,
207    pub sandbox: String,
208    pub image_tag: String,
209    pub backend: String,
210    pub base_image: Option<String>,
211    pub vcpus: Option<u32>,
212    pub memory_mb: Option<u64>,
213    pub created_at: String,
214}
215
216/// Options for taking a snapshot.
217#[derive(Debug, Default, Serialize)]
218pub struct TakeSnapshotOptions {
219    pub sandbox: String,
220    #[serde(skip_serializing_if = "Option::is_none")]
221    pub name: Option<String>,
222}
223
224/// Status of a detached command.
225#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
226#[serde(rename_all = "lowercase")]
227pub enum DetachedStatus {
228    Running,
229    Completed,
230    Failed,
231}
232
233/// A detached (background) command running in a sandbox.
234#[derive(Debug, Deserialize)]
235pub struct DetachedCommand {
236    pub id: String,
237    pub sandbox: String,
238    pub command: Vec<String>,
239    pub pid: u32,
240    pub status: DetachedStatus,
241    pub exit_code: Option<i32>,
242    pub started_at: String,
243}
244
245/// Response from detached command logs.
246#[derive(Debug, Deserialize)]
247pub struct DetachedLogsResponse {
248    pub stdout: Option<String>,
249    pub stderr: Option<String>,
250}
251
252// -- Browser types --
253
254/// A link extracted from a page.
255#[derive(Debug, Clone, Serialize, Deserialize)]
256pub struct PageLink {
257    pub text: String,
258    pub href: String,
259}
260
261/// Result of navigating to a page.
262#[derive(Debug, Clone, Serialize, Deserialize)]
263pub struct PageResult {
264    pub title: String,
265    pub url: String,
266    pub text: String,
267    pub links: Vec<PageLink>,
268}
269
270/// ARIA accessibility tree snapshot of a web page (v2).
271#[derive(Debug, Clone, Serialize, Deserialize)]
272pub struct AriaSnapshot {
273    /// ARIA tree as YAML.
274    pub snapshot: String,
275    /// Current page URL.
276    pub url: String,
277    /// Page title.
278    pub title: String,
279    /// Available ref IDs (e.g. `["e1", "e2"]`).
280    #[serde(default)]
281    pub refs: Vec<String>,
282}
283
284/// A browser interaction event for debugging and context recovery.
285#[derive(Debug, Clone, Serialize, Deserialize)]
286pub struct BrowserEvent {
287    /// Monotonic sequence number.
288    pub seq: u64,
289    /// Event type (e.g. "page.navigated", "page.clicked").
290    #[serde(rename = "type")]
291    pub event_type: String,
292    /// Page name.
293    pub page: String,
294    /// ISO 8601 timestamp.
295    pub ts: String,
296}
agentkernel_sdk/types.rs

agentkernel_sdk/
types.rs
