mycode-coding-agent 0.1.0__py3-none-any.whl

mycode/tools/base.py

@@ -0,0 +1,222 @@
+import asyncio
+import copy
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import ClassVar, Generic, TypeVar
+
+from pydantic import BaseModel, ConfigDict, ValidationError
+
+from mycode.permissions import (
+    PermissionChecker,
+    PermissionDecision,
+    PermissionRequest,
+    ToolCapability,
+    ToolPermissionProfile,
+    ToolRisk,
+)
+
+
+class ToolArgs(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+ArgsT = TypeVar("ArgsT")
+PydanticArgsT = TypeVar("PydanticArgsT", bound=ToolArgs)
+
+
+class ToolPermissionProfileError(ValueError):
+    pass
+
+
+class ToolArgumentValidationError(ValueError):
+    def __init__(self, errors: list[dict[str, object]]) -> None:
+        super().__init__("Invalid tool arguments")
+        self.errors = errors
+
+
+@dataclass(frozen=True)
+class ToolResult:
+    ok: bool
+    content: str = ""
+    error: str | None = None
+    metadata: dict[str, object] = field(default_factory=dict)
+
+    @classmethod
+    def success(
+        cls,
+        content: str,
+        metadata: dict[str, object] | None = None,
+    ) -> "ToolResult":
+        return cls(
+            ok=True,
+            content=content,
+            metadata={} if metadata is None else dict(metadata),
+        )
+
+    @classmethod
+    def failure(
+        cls,
+        error: str,
+        metadata: dict[str, object] | None = None,
+    ) -> "ToolResult":
+        return cls(
+            ok=False,
+            error=error,
+            metadata={} if metadata is None else dict(metadata),
+        )
+
+
+class BaseTool(ABC, Generic[ArgsT]):
+    name: ClassVar[str]
+    description: ClassVar[str]
+    capability: ClassVar[ToolCapability]
+    risk: ClassVar[ToolRisk]
+    # Tools must opt in explicitly. The scheduler also checks capability and
+    # risk, so a write/command/control tool cannot become concurrent by mistake.
+    concurrency_safe: ClassVar[bool] = False
+
+    @property
+    @abstractmethod
+    def input_schema(self) -> dict[str, object]:
+        """Return the JSON Schema accepted by this tool."""
+        raise NotImplementedError
+
+    def get_schema(self) -> dict[str, object]:
+        return {
+            "name": self.name,
+            "description": self.description,
+            "parameters": copy.deepcopy(self.input_schema),
+        }
+
+    def get_permission_profile(self) -> ToolPermissionProfile:
+        capability = getattr(self, "capability", None)
+        if capability is None:
+            raise ToolPermissionProfileError(
+                f"Tool must declare capability: {self.name}"
+            )
+
+        risk = getattr(self, "risk", None)
+        if risk is None:
+            raise ToolPermissionProfileError(
+                f"Tool must declare risk: {self.name}"
+            )
+
+        return ToolPermissionProfile(
+            capability=capability,
+            risk=risk,
+        )
+
+    def build_permission_request(self, args: ArgsT) -> PermissionRequest:
+        return PermissionRequest(
+            tool_name=self.name,
+            capability=self.capability,
+            action=self.name,
+            arguments=self.arguments_to_dict(args),
+        )
+
+    def check_permission(
+        self,
+        args: ArgsT,
+        permission_checker: PermissionChecker,
+    ) -> tuple[PermissionRequest, PermissionDecision]:
+        request = self.build_permission_request(args)
+        decision = permission_checker.check(
+            request,
+            self.get_permission_profile(),
+        )
+
+        return request, decision
+
+    @abstractmethod
+    def parse_arguments(self, arguments: dict[str, object]) -> ArgsT:
+        """Validate raw arguments and return the tool's execution value."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def arguments_to_dict(self, args: ArgsT) -> dict[str, object]:
+        """Serialize validated arguments for the permission request."""
+        raise NotImplementedError
+
+    @abstractmethod
+    async def run_authorized_async(
+        self,
+        args: ArgsT,
+        decision: PermissionDecision,
+    ) -> ToolResult:
+        """Execute validated, authorized arguments through the common path."""
+        raise NotImplementedError
+
+
+class SyncTool(BaseTool[ArgsT], Generic[ArgsT]):
+    """Adapt a synchronous tool implementation to the common async contract."""
+
+    def run(self, arguments: dict[str, object]) -> ToolResult:
+        try:
+            args = self.parse_arguments(arguments)
+        except ToolArgumentValidationError as error:
+            return ToolResult.failure(
+                error="Invalid tool arguments",
+                metadata={"validation_errors": error.errors},
+            )
+
+        return self.run_parsed(args)
+
+    def run_parsed(self, args: ArgsT) -> ToolResult:
+        try:
+            return self._run(args)
+        except Exception as error:  # noqa: BLE001 - normalize tool boundary failures
+            return ToolResult.failure(
+                error=f"Tool execution failed: {error}",
+                metadata={"exception_type": type(error).__name__},
+            )
+
+    def run_authorized(
+        self,
+        args: ArgsT,
+        decision: PermissionDecision,
+    ) -> ToolResult:
+        return self.run_parsed(args)
+
+    async def run_authorized_async(
+        self,
+        args: ArgsT,
+        decision: PermissionDecision,
+    ) -> ToolResult:
+        return await asyncio.to_thread(self.run_authorized, args, decision)
+
+    @abstractmethod
+    def _run(self, args: ArgsT) -> ToolResult:
+        pass
+
+
+class PydanticTool(SyncTool[PydanticArgsT], Generic[PydanticArgsT]):
+    """Base class for tools whose arguments are defined by a Pydantic model."""
+
+    args_model: ClassVar[type[PydanticArgsT]]
+
+    @property
+    def input_schema(self) -> dict[str, object]:
+        return _remove_schema_titles(self.args_model.model_json_schema())
+
+    def parse_arguments(self, arguments: dict[str, object]) -> PydanticArgsT:
+        try:
+            return self.args_model.model_validate(arguments)
+        except ValidationError as error:
+            raise ToolArgumentValidationError(error.errors()) from error
+
+    def arguments_to_dict(self, args: PydanticArgsT) -> dict[str, object]:
+        return args.model_dump()
+
+
+def _remove_schema_titles(value: object) -> object:
+    if isinstance(value, dict):
+        return {
+            key: _remove_schema_titles(item)
+            for key, item in value.items()
+            if key != "title"
+        }
+
+    if isinstance(value, list):
+        return [_remove_schema_titles(item) for item in value]
+
+    return value

mycode/tools/bounds.py

@@ -0,0 +1,14 @@
+"""Narrow normalization for bounded read-count arguments."""
+
+
+def clamp_positive_int_upper_bound(
+    value: object,
+    *,
+    upper_bound: int,
+) -> object:
+    """Clamp only genuine positive integer overflow; preserve all invalid inputs."""
+    if upper_bound < 1:
+        raise ValueError("upper_bound must be at least 1")
+    if type(value) is int and value > upper_bound:
+        return upper_bound
+    return value

mycode/tools/command_executor.py

@@ -0,0 +1,167 @@
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+import time
+
+from mycode.tools.base import ToolResult
+from mycode.tools.command_output import (
+    BoundedOutputCapture,
+    build_output_metadata,
+    finish_output_threads,
+    start_output_threads,
+)
+from mycode.tools.process_tree import (
+    create_process_tree_cleanup,
+    process_tree_popen_kwargs,
+)
+
+
+@dataclass(frozen=True)
+class CommandExecutionArgs:
+    command: list[str]
+    timeout_seconds: float
+    max_output_chars: int
+
+
+def execute_command(
+    *,
+    args: CommandExecutionArgs,
+    cwd: Path,
+    permission_metadata: dict[str, object],
+    permission_status: str,
+) -> ToolResult:
+    started_at = time.monotonic()
+    try:
+        process = subprocess.Popen(
+            args.command,
+            cwd=cwd,
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            shell=False,
+            **process_tree_popen_kwargs(),
+        )
+    except OSError as error:
+        return ToolResult.failure(
+            error=f"Command failed to start: {error}",
+            metadata={
+                **permission_metadata,
+                "exit_code": None,
+                "timed_out": False,
+                "duration_ms": _elapsed_milliseconds(started_at),
+                "permission_status": permission_status,
+                "exception_type": type(error).__name__,
+            },
+        )
+
+    process_tree_cleanup = create_process_tree_cleanup(process)
+    stdout_capture = BoundedOutputCapture(args.max_output_chars)
+    stderr_capture = BoundedOutputCapture(args.max_output_chars)
+    output_threads = start_output_threads(
+        process=process,
+        stdout_capture=stdout_capture,
+        stderr_capture=stderr_capture,
+    )
+
+    timed_out = False
+    output_capture_complete = True
+    process_tree_cleanup_success = True
+    returncode: int | None
+    try:
+        returncode = process.wait(timeout=args.timeout_seconds)
+    except subprocess.TimeoutExpired:
+        timed_out = True
+        returncode = None
+        process_tree_cleanup_success = process_tree_cleanup.close()
+        if not process_tree_cleanup_success:
+            process.kill()
+        process.wait()
+    finally:
+        process_tree_cleanup_success = (
+            process_tree_cleanup.close() and process_tree_cleanup_success
+        )
+        output_capture_complete = finish_output_threads(process, output_threads)
+
+    stdout = stdout_capture.snapshot()
+    stderr = stderr_capture.snapshot()
+    output_metadata = build_output_metadata(stdout=stdout, stderr=stderr)
+
+    metadata = {
+        **permission_metadata,
+        **output_metadata,
+        "exit_code": returncode,
+        "timed_out": timed_out,
+        "duration_ms": _elapsed_milliseconds(started_at),
+        "output_capture_complete": output_capture_complete,
+        "process_tree_cleanup_method": process_tree_cleanup.method,
+        "process_tree_cleanup_success": process_tree_cleanup_success,
+        "permission_status": permission_status,
+    }
+    if process_tree_cleanup.error is not None:
+        metadata["process_tree_cleanup_error"] = process_tree_cleanup.error
+
+    if timed_out:
+        timeout_error = f"Command timed out after {args.timeout_seconds:g} seconds."
+        captured_output = _format_captured_output(
+            stdout=stdout.content,
+            stderr=stderr.content,
+        )
+        return ToolResult.failure(
+            error=(
+                timeout_error
+                if captured_output == ""
+                else f"{timeout_error}\n\n{captured_output}"
+            ),
+            metadata=metadata,
+        )
+
+    content = _format_command_result(
+        exit_code=returncode,
+        stdout=stdout.content,
+        stderr=stderr.content,
+    )
+
+    if returncode != 0:
+        return ToolResult.failure(
+            error=content,
+            metadata=metadata,
+        )
+
+    return ToolResult.success(content=content, metadata=metadata)
+
+
+def _elapsed_milliseconds(started_at: float) -> int:
+    return max(0, round((time.monotonic() - started_at) * 1000))
+
+
+def _format_command_result(
+    *,
+    exit_code: int | None,
+    stdout: object,
+    stderr: object,
+) -> str:
+    parts = [f"Command exited with code {exit_code}."]
+    captured_output = _format_captured_output(stdout=stdout, stderr=stderr)
+    if captured_output:
+        parts.extend(["", captured_output])
+
+    return "\n".join(parts)
+
+
+def _format_captured_output(*, stdout: object, stderr: object) -> str:
+    sections: list[str] = []
+    final_newline = False
+    for label, value in (("STDOUT", stdout), ("STDERR", stderr)):
+        if not value:
+            continue
+        text = str(value)
+        final_newline = text.endswith(("\n", "\r"))
+        sections.append(f"{label}\n{text.rstrip(chr(10) + chr(13))}")
+
+    formatted = "\n\n".join(sections)
+    if formatted and final_newline:
+        return f"{formatted}\n"
+    return formatted

mycode/tools/command_output.py

@@ -0,0 +1,166 @@
+import subprocess
+import threading
+import time
+from collections import deque
+from dataclasses import dataclass
+
+
+OUTPUT_THREAD_JOIN_TIMEOUT_SECONDS = 1.0
+OUTPUT_THREAD_CLOSE_JOIN_TIMEOUT_SECONDS = 0.2
+
+
+@dataclass(frozen=True)
+class CapturedOutput:
+    content: str
+    chars: int
+    truncated: bool
+
+
+class BoundedOutputCapture:
+    def __init__(self, max_chars: int) -> None:
+        self.max_chars = max_chars
+        self._chars = 0
+        self._tail_chars = 0
+        self._chunks: deque[str] = deque()
+        self._lock = threading.Lock()
+
+    def append(self, chunk: str) -> None:
+        if chunk == "":
+            return
+
+        with self._lock:
+            self._chars += len(chunk)
+            if self.max_chars == 0:
+                return
+
+            if len(chunk) >= self.max_chars:
+                self._chunks.clear()
+                tail_chunk = chunk[-self.max_chars :]
+                self._chunks.append(tail_chunk)
+                self._tail_chars = len(tail_chunk)
+                return
+
+            self._chunks.append(chunk)
+            self._tail_chars += len(chunk)
+            self._trim_to_max_chars()
+
+    def snapshot(self) -> CapturedOutput:
+        with self._lock:
+            return CapturedOutput(
+                content="".join(self._chunks),
+                chars=self._chars,
+                truncated=self._chars > self.max_chars,
+            )
+
+    def _trim_to_max_chars(self) -> None:
+        overflow = self._tail_chars - self.max_chars
+        while overflow > 0 and self._chunks:
+            left = self._chunks[0]
+            if len(left) <= overflow:
+                self._chunks.popleft()
+                self._tail_chars -= len(left)
+                overflow -= len(left)
+                continue
+
+            self._chunks[0] = left[overflow:]
+            self._tail_chars -= overflow
+            break
+
+
+def start_output_threads(
+    *,
+    process: subprocess.Popen[str],
+    stdout_capture: BoundedOutputCapture,
+    stderr_capture: BoundedOutputCapture,
+) -> list[threading.Thread]:
+    threads: list[threading.Thread] = []
+    if process.stdout is not None:
+        threads.append(
+            threading.Thread(
+                target=_consume_output_stream,
+                args=(process.stdout, stdout_capture),
+                daemon=True,
+            )
+        )
+    if process.stderr is not None:
+        threads.append(
+            threading.Thread(
+                target=_consume_output_stream,
+                args=(process.stderr, stderr_capture),
+                daemon=True,
+            )
+        )
+
+    for thread in threads:
+        thread.start()
+
+    return threads
+
+
+def finish_output_threads(
+    process: subprocess.Popen[str],
+    threads: list[threading.Thread],
+) -> bool:
+    if _join_output_threads(threads, OUTPUT_THREAD_JOIN_TIMEOUT_SECONDS):
+        return True
+
+    _close_process_output_streams(process)
+    _join_output_threads(threads, OUTPUT_THREAD_CLOSE_JOIN_TIMEOUT_SECONDS)
+    return False
+
+
+def build_output_metadata(
+    *,
+    stdout: CapturedOutput,
+    stderr: CapturedOutput,
+) -> dict[str, object]:
+    return {
+        "stdout_chars": stdout.chars,
+        "stderr_chars": stderr.chars,
+        "stdout_truncated": stdout.truncated,
+        "stderr_truncated": stderr.truncated,
+        "output_truncation_strategy": "tail",
+    }
+
+
+def _consume_output_stream(
+    stream: object,
+    capture: BoundedOutputCapture,
+) -> None:
+    try:
+        while True:
+            try:
+                chunk = stream.read(8192)  # type: ignore[attr-defined]
+            except (OSError, ValueError):
+                break
+            if not chunk:
+                break
+            capture.append(str(chunk))
+    finally:
+        _close_stream(stream)
+
+
+def _join_output_threads(
+    threads: list[threading.Thread],
+    timeout_seconds: float,
+) -> bool:
+    deadline = time.monotonic() + timeout_seconds
+    for thread in threads:
+        remaining = max(0.0, deadline - time.monotonic())
+        thread.join(timeout=remaining)
+
+    return not any(thread.is_alive() for thread in threads)
+
+
+def _close_process_output_streams(process: subprocess.Popen[str]) -> None:
+    if process.stdout is not None:
+        _close_stream(process.stdout)
+    if process.stderr is not None:
+        _close_stream(process.stderr)
+
+
+def _close_stream(stream: object) -> None:
+    try:
+        stream.close()  # type: ignore[attr-defined]
+    except (OSError, ValueError):
+        pass