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

agent_engine/tools/shell/
start.rs
