use std::sync::Arc;
use rmcp::model::{JsonObject, Tool, ToolAnnotations};
use serde_json::{Value, json};
use crate::{
model::{
MAX_ARG_BYTES, MAX_ARGV_ITEMS, MAX_COMMAND_BYTES, MAX_ENV_ITEMS, MAX_PATH_BYTES,
MAX_STDIN_BYTES,
},
policy::ExecPolicy,
};
pub fn tools(policy: &ExecPolicy) -> Vec<Tool> {
vec![
shell_tool(policy),
read_tool(),
write_tool(),
signal_tool(),
resize_tool(),
]
}
pub fn get_tool(policy: &ExecPolicy, name: &str) -> Option<Tool> {
match name {
"shell" => Some(shell_tool(policy)),
"shell_read" => Some(read_tool()),
"shell_write" => Some(write_tool()),
"shell_signal" => Some(signal_tool()),
"shell_resize" => Some(resize_tool()),
_ => None,
}
}
fn shell_tool(policy: &ExecPolicy) -> Tool {
let (description, primary) = if policy.is_restricted() {
(
"Execute one permitted top-level program directly without a shell interpreter. Pass argv with the executable as argv[0]. Shell operators (|, &&, redirects, globbing, command substitution) are unavailable. foreground is the default and asks for the final result; a long foreground command transparently becomes an MCP Task on MCP 2026-07-28 when the client declares Tasks, otherwise it yields a processId fallback. background returns a processId immediately. interactive allocates a PTY and returns a processId. The executable policy is a top-level guardrail, not an OS sandbox.",
json!({
"argv": {
"type": "array",
"minItems": 1,
"maxItems": MAX_ARGV_ITEMS,
"items": {"type": "string", "maxLength": MAX_ARG_BYTES},
"description": "Executable and arguments. argv[0] is resolved and checked against the startup policy."
}
}),
)
} else {
(
"Execute an unrestricted shell command with the permissions of the user running shellvibe. foreground is the default and asks for the final result; a long foreground command transparently becomes an MCP Task when the client supports Tasks, otherwise it yields a processId fallback. background returns a processId immediately. interactive allocates a PTY and returns a processId for shell_read/shell_write/shell_signal/shell_resize.",
json!({
"command": {
"type": "string",
"minLength": 1,
"maxLength": MAX_COMMAND_BYTES,
"description": "Command passed to the configured shell using -c (or cmd.exe /C on Windows)."
}
}),
)
};
let mut properties = primary
.as_object()
.expect("primary schema must be object")
.clone();
properties.extend(common_shell_properties());
let required = if policy.is_restricted() {
json!(["argv"])
} else {
json!(["command"])
};
let schema = json!({
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"additionalProperties": false,
"required": required,
"properties": properties
});
Tool::new("shell", description, arc_object(schema))
.with_title("Run shell process")
.with_raw_output_schema(arc_object(tool_output_schema(shell_result_schema())))
.with_annotations(
ToolAnnotations::new()
.read_only(false)
.destructive(true)
.idempotent(false)
.open_world(true),
)
}
fn common_shell_properties() -> JsonObject {
serde_json::from_value(json!({
"cwd": {"type": "string", "maxLength": MAX_PATH_BYTES, "description": "Working directory for this process."},
"env": {
"type": "object",
"maxProperties": MAX_ENV_ITEMS,
"propertyNames": {"minLength": 1, "pattern": "^[^=]+$"},
"additionalProperties": {"type": "string", "maxLength": MAX_STDIN_BYTES},
"description": "Environment variables added or overridden for the child process. Top-level executable policy resolution uses shellvibe's own startup PATH."
},
"stdin": {"type": "string", "maxLength": MAX_STDIN_BYTES, "description": "Optional UTF-8 input written immediately after spawn."},
"execution": {
"type": "string",
"enum": ["foreground", "background", "interactive"],
"default": "foreground",
"description": "foreground asks for the final result and may transparently use MCP Tasks; background returns a process handle; interactive forces a PTY and returns a process handle."
},
"pty": {"type": "boolean", "default": false, "description": "Allocate a pseudo-terminal. interactive mode always enables PTY."},
"yieldMs": {"type": "integer", "minimum": 1, "description": "Override the foreground grace period before a long command becomes a Task or process-handle fallback."},
"timeoutMs": {"type": "integer", "minimum": 1, "description": "Optional per-call runtime limit. Values above the server --max-runtime ceiling are clamped."},
"rows": {"type": "integer", "minimum": 1, "maximum": 1000, "default": 24, "description": "Initial PTY rows."},
"cols": {"type": "integer", "minimum": 1, "maximum": 2000, "default": 80, "description": "Initial PTY columns."}
})).expect("common schema is an object")
}
fn read_tool() -> Tool {
Tool::new(
"shell_read",
"Canonical output retrieval for a managed process. Returns only events after the monotonic cursor and may wait up to waitMs for output or a state change. nextCursor is the cursor for the next read; hasMore means another immediate read is useful.",
arc_object(json!({
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"additionalProperties": false,
"required": ["processId"],
"properties": {
"processId": {"type": "string", "pattern": "^p_[0-9a-f]{32}$"},
"cursor": {"type": "integer", "minimum": 0, "default": 0},
"waitMs": {"type": "integer", "minimum": 0, "default": 0}
}
})),
)
.with_title("Read process output")
.with_raw_output_schema(arc_object(tool_output_schema(read_result_schema())))
.with_annotations(
ToolAnnotations::new()
.read_only(true)
.destructive(false)
.idempotent(true)
.open_world(false),
)
}
fn write_tool() -> Tool {
Tool::new(
"shell_write",
"Send UTF-8 input to a running process stdin/PTY and optionally close stdin to deliver EOF. This returns an acknowledgement and does not wait for resulting output; use shell_read to observe output.",
arc_object(json!({
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"additionalProperties": false,
"required": ["processId"],
"properties": {
"processId": {"type": "string", "pattern": "^p_[0-9a-f]{32}$"},
"data": {"type": "string", "maxLength": MAX_STDIN_BYTES},
"appendNewline": {"type": "boolean", "default": false},
"closeStdin": {"type": "boolean", "default": false, "description": "Drop the stdin/PTY writer after any data is written, delivering EOF where supported."}
},
"anyOf": [
{"required": ["data"]},
{"properties": {"closeStdin": {"const": true}}, "required": ["closeStdin"]}
]
})),
)
.with_title("Write process input")
.with_raw_output_schema(arc_object(tool_output_schema(write_result_schema())))
.with_annotations(
ToolAnnotations::new()
.read_only(false)
.destructive(true)
.idempotent(false)
.open_world(false),
)
}
fn signal_tool() -> Tool {
Tool::new(
"shell_signal",
"Send INT, TERM, or KILL to the managed process tree. The acknowledgement confirms the request was sent, not that the process has exited; use shell_read with waitMs to observe terminal state.",
arc_object(json!({
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"additionalProperties": false,
"required": ["processId", "signal"],
"properties": {
"processId": {"type": "string", "pattern": "^p_[0-9a-f]{32}$"},
"signal": {"type": "string", "enum": ["int", "term", "kill"]}
}
})),
)
.with_title("Signal process")
.with_raw_output_schema(arc_object(tool_output_schema(signal_result_schema())))
.with_annotations(
ToolAnnotations::new()
.read_only(false)
.destructive(true)
.idempotent(false)
.open_world(false),
)
}
fn resize_tool() -> Tool {
Tool::new(
"shell_resize",
"Resize a running PTY. This returns only the new dimensions and current status; accumulated terminal output remains available through shell_read.",
arc_object(json!({
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"additionalProperties": false,
"required": ["processId", "rows", "cols"],
"properties": {
"processId": {"type": "string", "pattern": "^p_[0-9a-f]{32}$"},
"rows": {"type": "integer", "minimum": 1, "maximum": 1000},
"cols": {"type": "integer", "minimum": 1, "maximum": 2000}
}
})),
)
.with_title("Resize PTY")
.with_raw_output_schema(arc_object(tool_output_schema(resize_result_schema())))
.with_annotations(
ToolAnnotations::new()
.read_only(false)
.destructive(false)
.idempotent(true)
.open_world(false),
)
}
fn tool_output_schema(success: Value) -> Value {
json!({
"$schema": "https://json-schema.org/draft/2020-12/schema",
"oneOf": [
success,
{
"type": "object",
"additionalProperties": false,
"required": ["error", "message"],
"properties": {
"error": {"const": "shellvibe_error"},
"message": {"type": "string"}
}
}
]
})
}
fn shell_result_schema() -> Value {
json!({
"type": "object",
"additionalProperties": false,
"required": ["processId", "status", "pty", "nextCursor"],
"properties": {
"processId": {"type": "string", "pattern": "^p_[0-9a-f]{32}$"},
"status": {"type": "string", "enum": ["running", "exited", "signaled", "timed_out", "cancelled", "failed"]},
"pid": {"type": "integer", "minimum": 0},
"pty": {"type": "boolean"},
"rows": {"type": "integer", "minimum": 1},
"cols": {"type": "integer", "minimum": 1},
"exitCode": {"type": "integer"},
"signal": {"type": "string"},
"elapsedMs": {"type": "integer", "minimum": 0},
"output": {"type": "string", "description": "Bounded ordered output tail present for completed foreground execution."},
"outputTruncated": {"type": "boolean"},
"nextCursor": {"type": "integer", "minimum": 0}
}
})
}
fn read_result_schema() -> Value {
json!({
"type": "object",
"additionalProperties": false,
"required": ["processId", "status", "events", "nextCursor", "hasMore", "cursorLost"],
"properties": {
"processId": {"type": "string", "pattern": "^p_[0-9a-f]{32}$"},
"status": {"type": "string", "enum": ["running", "exited", "signaled", "timed_out", "cancelled", "failed"]},
"events": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": ["cursor", "stream", "data"],
"properties": {
"cursor": {"type": "integer", "minimum": 1},
"stream": {"type": "string", "enum": ["stdout", "stderr", "pty"]},
"data": {"type": "string"}
}
}
},
"nextCursor": {"type": "integer", "minimum": 0},
"hasMore": {"type": "boolean"},
"cursorLost": {"type": "boolean"},
"exitCode": {"type": "integer"},
"signal": {"type": "string"},
"elapsedMs": {"type": "integer", "minimum": 0}
}
})
}
fn write_result_schema() -> Value {
json!({
"type": "object",
"additionalProperties": false,
"required": ["processId", "acceptedBytes", "stdinClosed", "status"],
"properties": {
"processId": {"type": "string", "pattern": "^p_[0-9a-f]{32}$"},
"acceptedBytes": {"type": "integer", "minimum": 0},
"stdinClosed": {"type": "boolean"},
"status": {"type": "string", "enum": ["running", "exited", "signaled", "timed_out", "cancelled", "failed"]}
}
})
}
fn signal_result_schema() -> Value {
json!({
"type": "object",
"additionalProperties": false,
"required": ["processId", "signal", "accepted", "status"],
"properties": {
"processId": {"type": "string", "pattern": "^p_[0-9a-f]{32}$"},
"signal": {"type": "string", "enum": ["int", "term", "kill"]},
"accepted": {"type": "boolean"},
"status": {"type": "string", "enum": ["running", "exited", "signaled", "timed_out", "cancelled", "failed"]}
}
})
}
fn resize_result_schema() -> Value {
json!({
"type": "object",
"additionalProperties": false,
"required": ["processId", "rows", "cols", "status"],
"properties": {
"processId": {"type": "string", "pattern": "^p_[0-9a-f]{32}$"},
"rows": {"type": "integer", "minimum": 1, "maximum": 1000},
"cols": {"type": "integer", "minimum": 1, "maximum": 2000},
"status": {"type": "string", "enum": ["running", "exited", "signaled", "timed_out", "cancelled", "failed"]}
}
})
}
fn arc_object(value: Value) -> Arc<JsonObject> {
Arc::new(
value
.as_object()
.expect("schema must be a JSON object")
.clone(),
)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn unrestricted_schema_exposes_command_not_argv() {
let tool = shell_tool(&ExecPolicy::Unrestricted);
let properties = tool
.input_schema
.get("properties")
.unwrap()
.as_object()
.unwrap();
assert!(properties.contains_key("command"));
assert!(!properties.contains_key("argv"));
}
#[test]
fn restricted_schema_exposes_argv_not_command() {
let policy = ExecPolicy::Deny {
names: Default::default(),
paths: Default::default(),
};
let tool = shell_tool(&policy);
let properties = tool
.input_schema
.get("properties")
.unwrap()
.as_object()
.unwrap();
assert!(properties.contains_key("argv"));
assert!(!properties.contains_key("command"));
}
}