agent_engine/tools/shell/
start.rs

1//! `shell_start` tool — create a new interactive shell session.
2
3use crate::tools::{Tool, ToolContext};
4use crate::{Result, RuntimeError};
5use serde_json::{json, Value};
6
7pub struct ShellStartTool;
8
9#[async_trait::async_trait]
10impl Tool for ShellStartTool {
11    fn name(&self) -> &str {
12        "shell_start"
13    }
14
15    fn description(&self) -> &str {
16        "Start a new interactive shell session with a PTY. Returns a session ID and the initial output. Use shell_send to interact and shell_end to close."
17    }
18
19    fn parameters(&self) -> Value {
20        json!({
21            "type": "object",
22            "properties": {
23                "command": {
24                    "type": "string",
25                    "description": "Command to run (default: user's default shell). Examples: 'bash', 'python3', 'ssh user@host'"
26                },
27                "working_directory": {
28                    "type": "string",
29                    "description": "Working directory for the session (default: current directory)"
30                },
31                "env": {
32                    "type": "object",
33                    "description": "Additional environment variables as key-value pairs",
34                    "additionalProperties": { "type": "string" }
35                },
36                "rows": {
37                    "type": "integer",
38                    "description": "Terminal rows (default: from config, fallback 24)"
39                },
40                "cols": {
41                    "type": "integer",
42                    "description": "Terminal columns (default: from config, fallback 80)"
43                },
44                "readiness_timeout_ms": {
45                    "type": "integer",
46                    "description": "Override output readiness timeout for this session (ms)"
47                },
48                "idle_timeout": {
49                    "type": "integer",
50                    "description": "Override idle timeout for this session (seconds)"
51                }
52            },
53            "required": []
54        })
55    }
56
57    async fn execute(&self, params: Value, ctx: ToolContext) -> Result<String> {
58        let mgr = ctx
59            .capabilities
60            .session_manager
61            .as_ref()
62            .ok_or_else(|| RuntimeError::Tool("Shell sessions not available".into()))?;
63
64        let command = params["command"].as_str().map(|s| s.to_string());
65        let working_directory = params["working_directory"].as_str().map(|s| s.to_string());
66        let rows = params["rows"].as_u64().map(|r| r as u16);
67        let cols = params["cols"].as_u64().map(|c| c as u16);
68        let readiness_timeout_ms = params["readiness_timeout_ms"].as_u64();
69        let idle_timeout = params["idle_timeout"].as_u64();
70
71        let env = params["env"]
72            .as_object()
73            .map(|obj| {
74                obj.iter()
75                    .filter_map(|(k, v)| v.as_str().map(|s| (k.clone(), s.to_string())))
76                    .collect()
77            })
78            .unwrap_or_default();
79
80        let opts = super::SessionOpts {
81            command,
82            working_directory,
83            env,
84            rows,
85            cols,
86            readiness_timeout_ms,
87            idle_timeout,
88        };
89
90        let (session_id, output, status) = mgr
91            .create_session(
92                opts,
93                ctx.channels.tx_delta.as_ref(),
94                ctx.limits.max_tool_buffer,
95            )
96            .await?;
97
98        let mut result = format!("[Session {} | {}]\n", session_id, status);
99        if !output.is_empty() {
100            result.push_str(&output);
101        }
102        Ok(result)
103    }
104}
agent_engine/tools/shell/start.rs

agent_engine/tools/shell/
start.rs
