mirror of
https://github.com/hanzoai/stack.git
synced 2026-11-19 03:06:57 +00:00
326 lines
9.4 KiB
Python
326 lines
9.4 KiB
Python
"""Background process execution tool."""
|
|
|
|
import os
|
|
import uuid
|
|
import subprocess
|
|
from typing import Unpack, Optional, Annotated, TypedDict, final, override
|
|
from pathlib import Path
|
|
from datetime import datetime
|
|
|
|
from pydantic import Field
|
|
from mcp.server.fastmcp import Context as MCPContext
|
|
|
|
from hanzo_mcp.tools.common.base import BaseTool
|
|
from hanzo_mcp.tools.common.context import create_tool_context
|
|
from hanzo_mcp.tools.common.permissions import PermissionManager
|
|
|
|
Command = Annotated[
|
|
str,
|
|
Field(
|
|
description="The command to execute in the background",
|
|
min_length=1,
|
|
),
|
|
]
|
|
|
|
WorkingDir = Annotated[
|
|
Optional[str],
|
|
Field(
|
|
description="Working directory for the command",
|
|
default=None,
|
|
),
|
|
]
|
|
|
|
Name = Annotated[
|
|
Optional[str],
|
|
Field(
|
|
description="Name for the background process (for identification)",
|
|
default=None,
|
|
),
|
|
]
|
|
|
|
LogToFile = Annotated[
|
|
bool,
|
|
Field(
|
|
description="Whether to log output to file",
|
|
default=True,
|
|
),
|
|
]
|
|
|
|
Env = Annotated[
|
|
Optional[dict[str, str]],
|
|
Field(
|
|
description="Environment variables to set",
|
|
default=None,
|
|
),
|
|
]
|
|
|
|
|
|
class RunBackgroundParams(TypedDict, total=False):
|
|
"""Parameters for running background commands."""
|
|
|
|
command: str
|
|
working_dir: Optional[str]
|
|
name: Optional[str]
|
|
log_to_file: bool
|
|
env: Optional[dict[str, str]]
|
|
|
|
|
|
class BackgroundProcess:
|
|
"""Represents a running background process."""
|
|
|
|
def __init__(
|
|
self,
|
|
process_id: str,
|
|
command: str,
|
|
name: str,
|
|
working_dir: str,
|
|
log_file: Optional[Path],
|
|
process: subprocess.Popen,
|
|
):
|
|
self.process_id = process_id
|
|
self.command = command
|
|
self.name = name
|
|
self.working_dir = working_dir
|
|
self.log_file = log_file
|
|
self.process = process
|
|
self.start_time = datetime.now()
|
|
self.end_time: Optional[datetime] = None
|
|
|
|
@property
|
|
def is_running(self) -> bool:
|
|
"""Check if process is still running."""
|
|
return self.process.poll() is None
|
|
|
|
@property
|
|
def pid(self) -> int:
|
|
"""Get process ID."""
|
|
return self.process.pid
|
|
|
|
@property
|
|
def return_code(self) -> Optional[int]:
|
|
"""Get return code if process has finished."""
|
|
return self.process.poll()
|
|
|
|
def terminate(self) -> None:
|
|
"""Terminate the process."""
|
|
if self.is_running:
|
|
self.process.terminate()
|
|
self.end_time = datetime.now()
|
|
|
|
def kill(self) -> None:
|
|
"""Kill the process forcefully."""
|
|
if self.is_running:
|
|
self.process.kill()
|
|
self.end_time = datetime.now()
|
|
|
|
def to_dict(self) -> dict:
|
|
"""Convert to dictionary for display."""
|
|
return {
|
|
"id": self.process_id,
|
|
"name": self.name,
|
|
"command": self.command,
|
|
"pid": self.pid,
|
|
"working_dir": self.working_dir,
|
|
"log_file": str(self.log_file) if self.log_file else None,
|
|
"start_time": self.start_time.isoformat(),
|
|
"end_time": self.end_time.isoformat() if self.end_time else None,
|
|
"is_running": self.is_running,
|
|
"return_code": self.return_code,
|
|
}
|
|
|
|
|
|
@final
|
|
class RunBackgroundTool(BaseTool):
|
|
"""Tool for running commands in the background."""
|
|
|
|
# Class variable to store running processes
|
|
_processes: dict[str, BackgroundProcess] = {}
|
|
|
|
def __init__(self, permission_manager: PermissionManager):
|
|
"""Initialize the background runner tool.
|
|
|
|
Args:
|
|
permission_manager: Permission manager for access control
|
|
"""
|
|
self.permission_manager = permission_manager
|
|
self.log_dir = Path.home() / ".hanzo" / "logs"
|
|
self.log_dir.mkdir(parents=True, exist_ok=True)
|
|
|
|
@property
|
|
@override
|
|
def name(self) -> str:
|
|
"""Get the tool name."""
|
|
return "run_background"
|
|
|
|
@property
|
|
@override
|
|
def description(self) -> str:
|
|
"""Get the tool description."""
|
|
return """Run a command in the background, allowing it to continue running.
|
|
|
|
Perfect for:
|
|
- Starting development servers (npm run dev, python -m http.server)
|
|
- Running long-running processes (file watchers, build processes)
|
|
- Starting services that need to keep running
|
|
- Running multiple processes concurrently
|
|
|
|
Features:
|
|
- Runs process in background, returns immediately
|
|
- Optional logging to ~/.hanzo/logs
|
|
- Process tracking with unique IDs
|
|
- Working directory support
|
|
- Environment variable support
|
|
|
|
Use 'processes' tool to list running processes
|
|
Use 'pkill' tool to terminate processes
|
|
Use 'logs' tool to view process output
|
|
|
|
Examples:
|
|
- run_background --command "npm run dev" --name "frontend-server"
|
|
- run_background --command "python app.py" --working-dir "/path/to/app"
|
|
"""
|
|
|
|
@override
|
|
async def call(
|
|
self,
|
|
ctx: MCPContext,
|
|
**params: Unpack[RunBackgroundParams],
|
|
) -> str:
|
|
"""Execute a command in the background.
|
|
|
|
Args:
|
|
ctx: MCP context
|
|
**params: Tool parameters
|
|
|
|
Returns:
|
|
Information about the started process
|
|
"""
|
|
tool_ctx = create_tool_context(ctx)
|
|
await tool_ctx.set_tool_info(self.name)
|
|
|
|
# Extract parameters
|
|
command = params.get("command")
|
|
if not command:
|
|
return "Error: command is required"
|
|
|
|
working_dir = params.get("working_dir", os.getcwd())
|
|
name = params.get("name", command.split()[0])
|
|
log_to_file = params.get("log_to_file", True)
|
|
env = params.get("env")
|
|
|
|
# Resolve absolute path for working directory
|
|
abs_working_dir = os.path.abspath(working_dir)
|
|
|
|
# Check permissions
|
|
if not self.permission_manager.has_permission(abs_working_dir):
|
|
return f"Permission denied: {abs_working_dir}"
|
|
|
|
# Check if working directory exists
|
|
if not os.path.exists(abs_working_dir):
|
|
return f"Working directory does not exist: {abs_working_dir}"
|
|
|
|
# Generate process ID
|
|
process_id = str(uuid.uuid4())[:8]
|
|
|
|
# Setup logging
|
|
log_file = None
|
|
if log_to_file:
|
|
log_filename = f"{process_id}_{name.replace(' ', '_')}_{datetime.now().strftime('%Y%m%d_%H%M%S')}.log"
|
|
log_file = self.log_dir / log_filename
|
|
|
|
await tool_ctx.info(f"Starting background process: {name}")
|
|
|
|
try:
|
|
# Prepare environment
|
|
process_env = os.environ.copy()
|
|
if env:
|
|
process_env.update(env)
|
|
|
|
# Open log file for writing
|
|
if log_file:
|
|
log_handle = open(log_file, "w")
|
|
stdout = log_handle
|
|
stderr = subprocess.STDOUT
|
|
else:
|
|
stdout = subprocess.DEVNULL
|
|
stderr = subprocess.DEVNULL
|
|
|
|
# Start the process
|
|
process = subprocess.Popen(
|
|
command,
|
|
shell=True,
|
|
cwd=abs_working_dir,
|
|
env=process_env,
|
|
stdout=stdout,
|
|
stderr=stderr,
|
|
# Don't wait for process to complete
|
|
start_new_session=True, # Detach from parent process group
|
|
)
|
|
|
|
# Create process object
|
|
bg_process = BackgroundProcess(
|
|
process_id=process_id,
|
|
command=command,
|
|
name=name,
|
|
working_dir=abs_working_dir,
|
|
log_file=log_file,
|
|
process=process,
|
|
)
|
|
|
|
# Store in class variable
|
|
RunBackgroundTool._processes[process_id] = bg_process
|
|
|
|
# Clean up finished processes
|
|
self._cleanup_finished_processes()
|
|
|
|
await tool_ctx.info(
|
|
f"Process started with ID: {process_id}, PID: {process.pid}"
|
|
)
|
|
|
|
# Return process information
|
|
return f"""Background process started successfully!
|
|
|
|
Process ID: {process_id}
|
|
Name: {name}
|
|
PID: {process.pid}
|
|
Command: {command}
|
|
Working Directory: {abs_working_dir}
|
|
Log File: {log_file if log_file else "Not logging"}
|
|
|
|
Use 'processes' to list all running processes
|
|
Use 'pkill --id {process_id}' to stop this process
|
|
Use 'logs --id {process_id}' to view output (if logging enabled)
|
|
"""
|
|
|
|
except Exception as e:
|
|
await tool_ctx.error(f"Failed to start background process: {str(e)}")
|
|
return f"Error starting background process: {str(e)}"
|
|
|
|
@classmethod
|
|
def get_processes(cls) -> dict[str, BackgroundProcess]:
|
|
"""Get all tracked processes."""
|
|
return cls._processes
|
|
|
|
@classmethod
|
|
def get_process(cls, process_id: str) -> Optional[BackgroundProcess]:
|
|
"""Get a specific process by ID."""
|
|
return cls._processes.get(process_id)
|
|
|
|
def _cleanup_finished_processes(self) -> None:
|
|
"""Remove finished processes that have been terminated for a while."""
|
|
now = datetime.now()
|
|
to_remove = []
|
|
|
|
for process_id, process in RunBackgroundTool._processes.items():
|
|
if not process.is_running and process.end_time:
|
|
# Keep finished processes for 5 minutes for log access
|
|
if (now - process.end_time).total_seconds() > 300:
|
|
to_remove.append(process_id)
|
|
|
|
for process_id in to_remove:
|
|
del RunBackgroundTool._processes[process_id]
|
|
|
|
def register(self, mcp_server) -> None:
|
|
"""Register this tool with the MCP server."""
|
|
pass
|