shellvibe 0.3.3

Observable MCP shell access with process lifecycle controls and modern Tasks support
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"));
    }
}