PyPI - run-command-tool - Versions diffs - 0.1.0__tar.gz - Mend

@@ -0,0 +1,188 @@
+"""
+run_command Tool
+================
+Execute a shell command as a subprocess and return its stdout, stderr,
+and exit code.
+Parameters:
+  command             - The full command line to run (required).
+  cwd                 - Absolute working directory path (optional).
+                        Defaults to the current process working directory.
+  timeout             - Max seconds to wait before killing the process (optional).
+                        Default 60 seconds. Set 0 to disable.
+  wait_ms_before_async- Wait this many milliseconds for output, then return
+                        without waiting for the process to finish (background mode).
+                        Default 0 = wait until the process exits.
+"""
+import asyncio
+import logging
+import os
+import sys
+from typing import Any, Dict, Optional
+from openchadpy.tool_base import ToolBase
+logger = logging.getLogger(__name__)
+DEFAULT_TIMEOUT_S = 60
+MAX_OUTPUT_CHARS = 50_000   # cap stdout/stderr to avoid flooding context
+class Tool(ToolBase):
+    name = "run_command"
+    description = (
+        "Execute a shell command as a subprocess and return its stdout, stderr, "
+        "and exit code. "
+        "Use for running scripts, build tools, tests, package managers, or any "
+        "CLI command. "
+        "Set wait_ms_before_async to a small value to launch a long-running "
+        "process in the background and get early output."
+    )
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "command": {
+                "type": "string",
+                "description": "The full command line to execute.",
+            },
+            "cwd": {
+                "type": "string",
+                "description": (
+                    "Absolute path of the working directory. "
+                    "Defaults to the current process working directory."
+                ),
+            },
+            "timeout": {
+                "type": "integer",
+                "description": (
+                    "Max seconds to wait before killing the process. "
+                    "Default 60. Set 0 to disable the timeout."
+                ),
+            },
+            "wait_ms_before_async": {
+                "type": "integer",
+                "description": (
+                    "Wait this many milliseconds for output, then return early "
+                    "without waiting for the process to finish (background / fire-and-forget mode). "
+                    "Default 0 = wait until process exits."
+                ),
+            },
+        },
+        "required": ["command"],
+    }
+    allowed_callers = ["direct", "code_execution"]
+    async def execute(self, **kwargs) -> Dict[str, Any]:  # noqa: C901
+        command: str = kwargs.get("command", "").strip()
+        cwd: Optional[str] = kwargs.get("cwd")
+        timeout_s: int = int(kwargs.get("timeout", DEFAULT_TIMEOUT_S))
+        wait_ms: int = int(kwargs.get("wait_ms_before_async", 0))
+        if not command:
+            return {"error": "command is required and must not be empty."}
+        # Validate / resolve cwd
+        if cwd:
+            if not os.path.isdir(cwd):
+                return {"error": f"cwd does not exist or is not a directory: {cwd!r}"}
+        else:
+            cwd = os.getcwd()
+        # Choose shell
+        is_windows = sys.platform.startswith("win")
+        if is_windows:
+            # Use PowerShell on Windows for consistency with the IDE
+            shell_args = ["powershell", "-NonInteractive", "-Command", command]
+        else:
+            shell_args = ["/bin/sh", "-c", command]
+        logger.info(f"[run_command] cwd={cwd!r} cmd={command!r}")
+        try:
+            proc = await asyncio.create_subprocess_exec(
+                *shell_args,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                cwd=cwd,
+                env={**os.environ, "PAGER": "cat"},
+            )
+        except Exception as e:
+            logger.error(f"[run_command] failed to start process: {e}")
+            return {"error": f"Failed to start process: {e}"}
+        # ── Background mode: wait only wait_ms then return early ──────
+        if wait_ms > 0:
+            try:
+                stdout_bytes, stderr_bytes = await asyncio.wait_for(
+                    proc.communicate(), timeout=wait_ms / 1000.0
+                )
+                exit_code = proc.returncode
+                background = False
+            except asyncio.TimeoutError:
+                # Process is still running; collect whatever was buffered
+                stdout_bytes = b""
+                stderr_bytes = b""
+                exit_code = None
+                background = True
+        else:
+            # ── Foreground mode: wait up to timeout ───────────────────
+            try:
+                wait_coro = proc.communicate()
+                if timeout_s > 0:
+                    stdout_bytes, stderr_bytes = await asyncio.wait_for(
+                        wait_coro, timeout=float(timeout_s)
+                    )
+                else:
+                    stdout_bytes, stderr_bytes = await wait_coro
+                exit_code = proc.returncode
+                background = False
+            except asyncio.TimeoutError:
+                proc.kill()
+                try:
+                    stdout_bytes, stderr_bytes = await proc.communicate()
+                except Exception:
+                    stdout_bytes = b""
+                    stderr_bytes = b""
+                exit_code = proc.returncode
+                background = False
+                return {
+                    "error": (
+                        f"Command timed out after {timeout_s}s and was killed. "
+                        "Increase timeout or use wait_ms_before_async for long-running commands."
+                    ),
+                    "stdout": _decode_cap(stdout_bytes),
+                    "stderr": _decode_cap(stderr_bytes),
+                    "exit_code": exit_code,
+                    "cwd": cwd,
+                    "command": command,
+                }
+        stdout_str = _decode_cap(stdout_bytes)
+        stderr_str = _decode_cap(stderr_bytes)
+        result: Dict[str, Any] = {
+            "command": command,
+            "cwd": cwd,
+            "exit_code": exit_code,
+            "background": background,
+            "stdout": stdout_str,
+            "stderr": stderr_str,
+        }
+        if exit_code is not None and exit_code != 0:
+            result["warning"] = f"Process exited with code {exit_code}."
+        logger.info(
+            f"[run_command] exit_code={exit_code} background={background} "
+            f"stdout_len={len(stdout_str)} stderr_len={len(stderr_str)}"
+        )
+        return result
+def _decode_cap(data: bytes) -> str:
+    """Decode bytes and cap to MAX_OUTPUT_CHARS to avoid context flooding."""
+    text = data.decode("utf-8", errors="replace")
+    if len(text) > MAX_OUTPUT_CHARS:
+        text = text[:MAX_OUTPUT_CHARS] + f"\n... [truncated, {len(text)} total chars]"
+    return text

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: run_command_tool
+Version: 0.1.0
+Summary: Execute a shell command as a subprocess and return its stdout, stderr.
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+Requires-Dist: openchadpy>=0.1.23

@@ -0,0 +1,9 @@
+[project]
+name = "run_command_tool"
+version = "0.1.0"
+description = "Execute a shell command as a subprocess and return its stdout, stderr."
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "openchadpy>=0.1.23",
+]

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: run_command_tool
+Version: 0.1.0
+Summary: Execute a shell command as a subprocess and return its stdout, stderr.
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+Requires-Dist: openchadpy>=0.1.23

@@ -0,0 +1,9 @@
+README.md
+pyproject.toml
+run_command_tool/__init__.py
+run_command_tool/main.py
+run_command_tool.egg-info/PKG-INFO
+run_command_tool.egg-info/SOURCES.txt
+run_command_tool.egg-info/dependency_links.txt
+run_command_tool.egg-info/requires.txt
+run_command_tool.egg-info/top_level.txt

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build =
+tag_date = 0

run-command-tool 0.1.0__tar.gz