ai-push-hooks 0.2.1 → 0.3.1

package/src/ai_push_hooks/executors/runners/process.py

@@ -0,0 +1,464 @@
+"""Common shell-free child-process execution for runner adapters."""
+
+from __future__ import annotations
+
+import math
+import os
+import pathlib
+import signal
+import stat
+import subprocess
+import threading
+import time
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+
+from ...paths import path_is_link_or_reparse
+from .contracts import (
+    RunnerError,
+    RunnerExecutableNotFoundError,
+    RunnerSignalError,
+    RunnerTimeoutError,
+    bounded_diagnostic,
+)
+
+
+PROCESS_CHUNK_BYTES = 64 * 1024
+# Agent CLIs commonly emit multi-megabyte JSONL event streams.  This remains a
+# hard per-stream bound; callers with a tighter budget can override it.
+DEFAULT_MAX_OUTPUT_BYTES = 16 * 1024 * 1024
+PROCESS_CLEANUP_GRACE_SECONDS = 1.0
+
+
+@dataclass(frozen=True, repr=False)
+class ProcessResult:
+    """Bounded child output.  Streams are never included in ``repr``."""
+
+    returncode: int
+    stdout: str
+    stderr: str
+    stdout_truncated: bool = False
+    stderr_truncated: bool = False
+    # Keep the original bounded bytes for callers that persist process output.
+    # The text fields above intentionally retain the runner's surrogateescape
+    # decoding contract.
+    stdout_bytes: bytes = b""
+    stderr_bytes: bytes = b""
+
+    def __repr__(self) -> str:
+        return (
+            "ProcessResult("
+            f"returncode={self.returncode!r}, stdout=<redacted>, stderr=<redacted>, "
+            f"stdout_truncated={self.stdout_truncated!r}, stderr_truncated={self.stderr_truncated!r})"
+        )
+
+
+def _read_bounded(
+    stream: object,
+    limit: int,
+    output: bytearray,
+    truncated: list[bool],
+    output_lock: threading.Lock,
+    output_limit_reached: threading.Event,
+) -> None:
+    read = getattr(stream, "read")
+    try:
+        while True:
+            try:
+                chunk = read(PROCESS_CHUNK_BYTES)
+            except (OSError, ValueError):
+                return
+            if not chunk:
+                return
+            with output_lock:
+                remaining = limit - len(output)
+                if remaining > 0:
+                    output.extend(chunk[:remaining])
+                if len(chunk) > remaining:
+                    truncated[0] = True
+                    output_limit_reached.set()
+    finally:
+        _close_pipe(stream)
+
+
+def _signal_process_group(process_group_id: int, signum: int) -> None:
+    try:
+        os.killpg(process_group_id, signum)
+    except (OSError, ProcessLookupError):
+        return
+
+
+def _process_group_exists(process_group_id: int) -> bool:
+    try:
+        os.killpg(process_group_id, 0)
+    except (OSError, ProcessLookupError):
+        return False
+    return True
+
+
+def _wait_process_until(process: subprocess.Popen[bytes], deadline: float) -> None:
+    while process.poll() is None:
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            return
+        try:
+            process.wait(timeout=min(remaining, 0.05))
+        except subprocess.TimeoutExpired:
+            continue
+
+
+def _stop_process(process: subprocess.Popen[bytes], deadline: float) -> None:
+    """Terminate this invocation's process group within one shared deadline."""
+
+    process_group_id = process.pid if os.name == "posix" else None
+    if process_group_id is not None:
+        # start_new_session=True makes the leader's pid the private process
+        # group id.  Do not gate this on leader.poll(): descendants can retain
+        # the pipes after the leader has already exited.
+        _signal_process_group(process_group_id, signal.SIGTERM)
+    elif process.poll() is None:
+        process.terminate()
+
+    _wait_process_until(process, deadline)
+
+    if process_group_id is not None:
+        while _process_group_exists(process_group_id):
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                _signal_process_group(process_group_id, signal.SIGKILL)
+                try:
+                    process.wait(timeout=0.1)
+                except subprocess.TimeoutExpired:
+                    pass
+                break
+            time.sleep(min(0.01, remaining))
+    elif process.poll() is None:
+        remaining = deadline - time.monotonic()
+        if remaining > 0:
+            try:
+                process.wait(timeout=remaining)
+            except subprocess.TimeoutExpired:
+                process.kill()
+                try:
+                    process.wait(timeout=0.1)
+                except subprocess.TimeoutExpired:
+                    pass
+
+
+def _close_pipe(stream: object) -> None:
+    """Close an unbuffered pipe through its owning stream object."""
+
+    try:
+        getattr(stream, "close")()
+    except (OSError, ValueError, AttributeError):
+        return
+
+
+def _finish_capture(
+    streams: tuple[object, ...],
+    threads: tuple[threading.Thread, ...],
+    deadline: float,
+) -> None:
+    """Bound all joins and force-close pipe fds if a reader remains blocked."""
+
+    for thread in threads:
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            break
+        thread.join(timeout=remaining)
+    if any(thread.is_alive() for thread in threads):
+        for stream in streams:
+            _close_pipe(stream)
+        for thread in threads:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                break
+            thread.join(timeout=remaining)
+    # Popen creates FileIO objects because bufsize=0. FileIO.close() does not
+    # flush buffered data and atomically relinquishes descriptor ownership, so
+    # repeated cleanup cannot later close a descriptor reused by another child.
+    for stream in streams:
+        _close_pipe(stream)
+
+
+def _captured_result(
+    returncode: int,
+    stdout: bytearray,
+    stderr: bytearray,
+    stdout_truncated: list[bool],
+    stderr_truncated: list[bool],
+    stdout_lock: threading.Lock,
+    stderr_lock: threading.Lock,
+) -> ProcessResult:
+    """Snapshot bounded streams for an exception without exposing them in it."""
+
+    with stdout_lock:
+        stdout_text = bytes(stdout).decode("utf-8", errors="surrogateescape")
+    with stderr_lock:
+        stderr_text = bytes(stderr).decode("utf-8", errors="surrogateescape")
+    return ProcessResult(
+        returncode=returncode,
+        stdout=stdout_text,
+        stderr=stderr_text,
+        stdout_truncated=stdout_truncated[0],
+        stderr_truncated=stderr_truncated[0],
+        stdout_bytes=bytes(stdout),
+        stderr_bytes=bytes(stderr),
+    )
+
+
+def run_process(
+    argv: Sequence[str],
+    *,
+    cwd: pathlib.Path,
+    input_text: str | None = None,
+    input_path: pathlib.Path | None = None,
+    timeout_seconds: float,
+    env: Mapping[str, str] | None = None,
+    max_output_bytes: int = DEFAULT_MAX_OUTPUT_BYTES,
+    max_stderr_bytes: int | None = None,
+) -> ProcessResult:
+    """Run an argv vector directly, with bounded concurrent stream capture.
+
+    ``shell=False`` is explicit and prompt text is written only to stdin.  The
+    environment is accepted for the child but is never inspected or included
+    in errors.  Non-zero exits are returned for adapter-specific normalization;
+    timeout and signal termination are raised as distinct fail-closed errors.
+    """
+
+    if not isinstance(argv, (tuple, list)) or not argv or any(
+        not isinstance(argument, str) or not argument or "\x00" in argument for argument in argv
+    ):
+        raise RunnerError("runner command must be a non-empty NUL-free argv vector")
+    if not isinstance(cwd, pathlib.Path):
+        cwd = pathlib.Path(cwd)
+    if not cwd.is_dir():
+        raise RunnerError("runner cwd must be an existing directory")
+    if (
+        isinstance(timeout_seconds, bool)
+        or not isinstance(timeout_seconds, (int, float))
+        or not math.isfinite(timeout_seconds)
+        or timeout_seconds <= 0
+    ):
+        raise RunnerError("runner timeout must be a finite number greater than zero")
+    if (
+        isinstance(max_output_bytes, bool)
+        or not isinstance(max_output_bytes, int)
+        or max_output_bytes < 0
+    ):
+        raise RunnerError("runner output bound must not be negative")
+    stderr_limit = max_output_bytes if max_stderr_bytes is None else max_stderr_bytes
+    if (
+        isinstance(stderr_limit, bool)
+        or not isinstance(stderr_limit, int)
+        or stderr_limit < 0
+    ):
+        raise RunnerError("runner stderr output bound must not be negative")
+    if input_text is not None and input_path is not None:
+        raise RunnerError("runner input_text and input_path are mutually exclusive")
+    input_file = None
+    if input_path is not None:
+        if not isinstance(input_path, pathlib.Path):
+            input_path = pathlib.Path(input_path)
+        if path_is_link_or_reparse(input_path):
+            raise RunnerError("runner input file must not be a symlink or reparse point")
+        descriptor = -1
+        try:
+            # O_NONBLOCK prevents opening a FIFO from waiting for a writer;
+            # O_NOFOLLOW closes the symlink race between validation and open.
+            flags = (
+                os.O_RDONLY
+                | os.O_NONBLOCK
+                | getattr(os, "O_CLOEXEC", 0)
+                | getattr(os, "O_NOFOLLOW", 0)
+            )
+            descriptor = os.open(input_path, flags)
+            if not stat.S_ISREG(os.fstat(descriptor).st_mode):
+                raise RunnerError("runner input file must be an ordinary regular file")
+            input_file = os.fdopen(descriptor, "rb", buffering=0)
+            descriptor = -1
+        except RunnerError:
+            raise
+        except (OSError, ValueError) as exc:
+            raise RunnerError("runner input file could not be opened safely") from exc
+        finally:
+            if descriptor >= 0:
+                os.close(descriptor)
+
+    popen_kwargs: dict[str, object] = {
+        "cwd": cwd,
+        "stdin": subprocess.PIPE,
+        "stdout": subprocess.PIPE,
+        "stderr": subprocess.PIPE,
+        "shell": False,
+        "env": dict(env) if env is not None else None,
+        # Buffered pipe wrappers cannot safely be bypassed with os.close(): the
+        # wrapper still owns the descriptor and may close a later reused fd in
+        # its destructor. Unbuffered FileIO makes close bounded and ownership
+        # explicit while the reader threads retain concurrent stream draining.
+        "bufsize": 0,
+    }
+    if os.name == "posix":
+        popen_kwargs["start_new_session"] = True
+    try:
+        process = subprocess.Popen(list(argv), **popen_kwargs)
+    except FileNotFoundError as exc:
+        if input_file is not None:
+            input_file.close()
+        raise RunnerExecutableNotFoundError(
+            "runner executable was not found",
+            details=bounded_diagnostic(argv[0]),
+        ) from exc
+    except OSError as exc:
+        if input_file is not None:
+            input_file.close()
+        raise RunnerError("runner process could not be started", details=type(exc).__name__) from exc
+
+    if process.stdout is None or process.stderr is None or process.stdin is None:
+        _stop_process(process, time.monotonic() + PROCESS_CLEANUP_GRACE_SECONDS)
+        if input_file is not None:
+            input_file.close()
+        raise RunnerError("runner process pipes were not available")
+
+    stdout = bytearray()
+    stderr = bytearray()
+    stdout_lock = threading.Lock()
+    stderr_lock = threading.Lock()
+    stdout_truncated = [False]
+    stderr_truncated = [False]
+    output_limit_reached = threading.Event()
+    stdout_thread = threading.Thread(
+        target=_read_bounded,
+        args=(
+            process.stdout,
+            max_output_bytes,
+            stdout,
+            stdout_truncated,
+            stdout_lock,
+            output_limit_reached,
+        ),
+        daemon=True,
+    )
+    stderr_thread = threading.Thread(
+        target=_read_bounded,
+        args=(
+            process.stderr,
+            stderr_limit,
+            stderr,
+            stderr_truncated,
+            stderr_lock,
+            output_limit_reached,
+        ),
+        daemon=True,
+    )
+    stdout_thread.start()
+    stderr_thread.start()
+
+    input_bytes = None if input_text is None else input_text.encode("utf-8", errors="surrogateescape")
+
+    def write_input() -> None:
+        try:
+            if input_file is not None:
+                while True:
+                    chunk = input_file.read(PROCESS_CHUNK_BYTES)
+                    if not chunk:
+                        break
+                    offset = 0
+                    while offset < len(chunk):
+                        written = process.stdin.write(chunk[offset:])
+                        if not written:
+                            return
+                        offset += written
+            elif input_bytes:
+                offset = 0
+                while offset < len(input_bytes):
+                    written = process.stdin.write(input_bytes[offset:])
+                    if not written:
+                        break
+                    offset += written
+        except (BrokenPipeError, OSError, ValueError):
+            pass
+        finally:
+            if input_file is not None:
+                _close_pipe(input_file)
+            _close_pipe(process.stdin)
+
+    input_thread = threading.Thread(target=write_input, daemon=True)
+    input_thread.start()
+    process_exited = threading.Event()
+    process_returncode: list[int | None] = [None]
+
+    def wait_for_process_exit() -> None:
+        process_returncode[0] = process.wait()
+        process_exited.set()
+
+    process_wait_thread = threading.Thread(target=wait_for_process_exit, daemon=True)
+    process_wait_thread.start()
+    returncode: int | None = None
+    timeout_cause: subprocess.TimeoutExpired | None = None
+    output_limit_cause = False
+    try:
+        deadline = time.monotonic() + timeout_seconds
+        while True:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                timeout_cause = subprocess.TimeoutExpired(list(argv), timeout_seconds)
+                break
+            if output_limit_reached.is_set():
+                # A short grace period preserves the natural exit status for
+                # commands that wrote their final bounded chunk and were
+                # already exiting.  A still-live child is stopped below
+                # rather than allowed to drain discarded output until timeout.
+                if process_exited.wait(timeout=min(remaining, 0.05)):
+                    returncode = process_returncode[0]
+                else:
+                    output_limit_cause = True
+                break
+            if process_exited.wait(timeout=min(remaining, 0.05)):
+                returncode = process_returncode[0]
+                break
+    finally:
+        cleanup_deadline = time.monotonic() + PROCESS_CLEANUP_GRACE_SECONDS
+        _stop_process(process, cleanup_deadline)
+        _finish_capture(
+            (process.stdin, process.stdout, process.stderr),
+            (input_thread, stdout_thread, stderr_thread, process_wait_thread),
+            cleanup_deadline,
+        )
+
+    if returncode is None:
+        returncode = process_returncode[0] if process_returncode[0] is not None else process.poll()
+    if timeout_cause is not None:
+        timeout_returncode = returncode if returncode is not None else -getattr(signal, "SIGKILL", 9)
+        process_result = _captured_result(
+            timeout_returncode,
+            stdout,
+            stderr,
+            stdout_truncated,
+            stderr_truncated,
+            stdout_lock,
+            stderr_lock,
+        )
+        error = RunnerTimeoutError("runner process exceeded its timeout")
+        setattr(error, "_process_result", process_result)
+        raise error from timeout_cause
+
+    if returncode is None:  # pragma: no cover - process.wait either returns or raises
+        raise RunnerError("runner process returned no exit status")
+    process_result = _captured_result(
+        returncode,
+        stdout,
+        stderr,
+        stdout_truncated,
+        stderr_truncated,
+        stdout_lock,
+        stderr_lock,
+    )
+    if returncode < 0 and not output_limit_cause:
+        error = RunnerSignalError(
+            "runner process terminated by signal",
+            details=str(-returncode),
+        )
+        setattr(error, "_process_result", process_result)
+        raise error
+    return process_result

package/src/ai_push_hooks/executors/runners/registry.py

@@ -0,0 +1,117 @@
+"""Static, lazy registry for the four built-in runner adapter types."""
+
+from __future__ import annotations
+
+import importlib
+import threading
+from dataclasses import dataclass
+from types import ModuleType
+from typing import Callable, Mapping
+
+from .contracts import (
+    Runner,
+    RunnerAdapterUnavailableError,
+    RunnerContractError,
+)
+
+
+KNOWN_RUNNER_TYPES = ("opencode", "codex", "claude", "command")
+
+
+@dataclass(frozen=True)
+class LazyRunnerSpec:
+    """Import and construct an adapter only when that type is selected."""
+
+    module: str
+    factory_name: str = "create_runner"
+
+    def load(self) -> Runner:
+        try:
+            module: ModuleType = importlib.import_module(self.module)
+        except ModuleNotFoundError as exc:
+            if exc.name == self.module:
+                raise RunnerAdapterUnavailableError(
+                    "selected runner adapter is not installed in this build"
+                ) from exc
+            raise RunnerAdapterUnavailableError(
+                "selected runner adapter could not load its dependency",
+                details=type(exc).__name__,
+            ) from exc
+        try:
+            factory: Callable[[], Runner] = getattr(module, self.factory_name)
+        except AttributeError as exc:
+            raise RunnerAdapterUnavailableError(
+                "selected runner adapter has no factory"
+            ) from exc
+        try:
+            runner = factory()
+        except RunnerAdapterUnavailableError:
+            raise
+        except Exception as exc:  # noqa: BLE001
+            raise RunnerAdapterUnavailableError(
+                "selected runner adapter could not be constructed",
+                details=type(exc).__name__,
+            ) from exc
+        if not callable(getattr(runner, "run", None)):
+            raise RunnerAdapterUnavailableError("selected runner does not implement run(request)")
+        return runner
+
+
+_DEFAULT_SPECS = {
+    "opencode": LazyRunnerSpec("ai_push_hooks.executors.runners.opencode"),
+    "codex": LazyRunnerSpec("ai_push_hooks.executors.runners.codex"),
+    "claude": LazyRunnerSpec("ai_push_hooks.executors.runners.claude"),
+    "command": LazyRunnerSpec("ai_push_hooks.executors.runners.command"),
+}
+
+
+class RunnerRegistry:
+    """A fixed registry; it intentionally has no runtime plugin registration API."""
+
+    def __init__(self, specs: Mapping[str, LazyRunnerSpec | Callable[[], Runner]] | None = None) -> None:
+        selected = _DEFAULT_SPECS if specs is None else dict(specs)
+        unknown = set(selected) - set(KNOWN_RUNNER_TYPES)
+        if unknown:
+            raise RunnerContractError(
+                "runner registry contains unsupported adapter types: " + ", ".join(sorted(unknown))
+            )
+        if set(selected) != set(KNOWN_RUNNER_TYPES):
+            raise RunnerContractError("runner registry must contain all four known adapter types")
+        self._specs = dict(selected)
+        self._loaded: dict[str, Runner] = {}
+        self._load_locks = {
+            runner_type: threading.Lock() for runner_type in KNOWN_RUNNER_TYPES
+        }
+
+    @property
+    def known_types(self) -> tuple[str, ...]:
+        return KNOWN_RUNNER_TYPES
+
+    def get(self, runner_type: str) -> Runner:
+        if runner_type not in self._specs:
+            raise RunnerContractError(f"unknown runner type: {runner_type!r}")
+        runner = self._loaded.get(runner_type)
+        if runner is not None:
+            return runner
+        # Initialization is serialized only for the selected adapter.  Other
+        # runner types may load concurrently, which matters for capability
+        # probes such as Claude's --help check.
+        with self._load_locks[runner_type]:
+            runner = self._loaded.get(runner_type)
+            if runner is None:
+                spec = self._specs[runner_type]
+                runner = spec.load() if isinstance(spec, LazyRunnerSpec) else spec()
+                self._loaded[runner_type] = runner
+            return runner
+
+    def __contains__(self, runner_type: object) -> bool:
+        return runner_type in self._specs
+
+
+DEFAULT_RUNNER_REGISTRY = RunnerRegistry()
+
+
+def get_runner(runner_type: str, *, registry: RunnerRegistry = DEFAULT_RUNNER_REGISTRY) -> Runner:
+    """Resolve one of the four static adapter types lazily."""
+
+    return registry.get(runner_type)