ai-push-hooks 0.3.0 → 0.3.2

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

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import math
 import os
 import pathlib
 import signal
@@ -58,6 +59,7 @@ def _read_bounded(
     output: bytearray,
     truncated: list[bool],
     output_lock: threading.Lock,
+    output_limit_reached: threading.Event,
 ) -> None:
     read = getattr(stream, "read")
     try:
@@ -74,6 +76,7 @@ def _read_bounded(
                     output.extend(chunk[:remaining])
                 if len(chunk) > remaining:
                     truncated[0] = True
+                    output_limit_reached.set()
     finally:
         _close_pipe(stream)
 
@@ -213,6 +216,7 @@ def run_process(
     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.
 
@@ -222,18 +226,39 @@ def run_process(
     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
+    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 timeout_seconds <= 0:
-        raise RunnerError("runner timeout must be greater than zero")
-    if max_output_bytes < 0:
+    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
@@ -241,7 +266,9 @@ def run_process(
         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")
+            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;
@@ -292,7 +319,9 @@ def run_process(
     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
+        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)
@@ -306,20 +335,39 @@ def run_process(
     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),
+        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, max_output_bytes, stderr, stderr_truncated, stderr_lock),
+        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")
+    input_bytes = (
+        None
+        if input_text is None
+        else input_text.encode("utf-8", errors="surrogateescape")
+    )
 
     def write_input() -> None:
         try:
@@ -350,25 +398,57 @@ def run_process(
 
     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:
-        returncode = process.wait(timeout=timeout_seconds)
-    except subprocess.TimeoutExpired as exc:
-        timeout_cause = exc
+        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),
+            (input_thread, stdout_thread, stderr_thread, process_wait_thread),
             cleanup_deadline,
         )
 
     if returncode is None:
-        returncode = process.poll()
+        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)
+        timeout_returncode = (
+            returncode if returncode is not None else -getattr(signal, "SIGKILL", 9)
+        )
         process_result = _captured_result(
             timeout_returncode,
             stdout,
@@ -393,7 +473,7 @@ def run_process(
         stdout_lock,
         stderr_lock,
     )
-    if returncode < 0:
+    if returncode < 0 and not output_limit_cause:
         error = RunnerSignalError(
             "runner process terminated by signal",
             details=str(-returncode),

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

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import importlib
+import threading
 from dataclasses import dataclass
 from types import ModuleType
 from typing import Callable, Mapping
@@ -52,7 +53,9 @@ class LazyRunnerSpec:
                 details=type(exc).__name__,
             ) from exc
         if not callable(getattr(runner, "run", None)):
-            raise RunnerAdapterUnavailableError("selected runner does not implement run(request)")
+            raise RunnerAdapterUnavailableError(
+                "selected runner does not implement run(request)"
+            )
         return runner
 
 
@@ -67,17 +70,25 @@ _DEFAULT_SPECS = {
 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:
+    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))
+                "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")
+            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, ...]:
@@ -86,10 +97,19 @@ class RunnerRegistry:
     def get(self, runner_type: str) -> Runner:
         if runner_type not in self._specs:
             raise RunnerContractError(f"unknown runner type: {runner_type!r}")
-        if runner_type not in self._loaded:
-            spec = self._specs[runner_type]
-            self._loaded[runner_type] = spec.load() if isinstance(spec, LazyRunnerSpec) else spec()
-        return self._loaded[runner_type]
+        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
@@ -98,7 +118,9 @@ class RunnerRegistry:
 DEFAULT_RUNNER_REGISTRY = RunnerRegistry()
 
 
-def get_runner(runner_type: str, *, registry: RunnerRegistry = DEFAULT_RUNNER_REGISTRY) -> Runner:
+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)

package/src/ai_push_hooks/executors/step_commands.py

@@ -19,7 +19,13 @@ from typing import Any
 
 from ..artifacts import ArtifactStore
 from ..paths import path_is_link_or_reparse
-from ..types import HookError, ModuleRuntimeState, RuntimeContext, StepConfig
+from ..types import (
+    DEFAULT_STEP_COMMAND_TIMEOUT_SECONDS,
+    HookError,
+    ModuleRuntimeState,
+    RuntimeContext,
+    StepConfig,
+)
 from .runners.contracts import bounded_diagnostic, redact_diagnostic
 from .runners.process import (
     DEFAULT_MAX_OUTPUT_BYTES,
@@ -27,7 +33,6 @@ from .runners.process import (
     run_process,
 )
 
-DEFAULT_STEP_COMMAND_TIMEOUT_SECONDS = 60
 STEP_COMMAND_STDOUT_ARTIFACT = "stdout.txt"
 STEP_COMMAND_STDERR_ARTIFACT = "stderr.txt"
 STEP_COMMAND_RESULT_ARTIFACT = "result.json"
@@ -74,7 +79,10 @@ class StepCommandResult:
             raise TypeError("step command returncode must be an integer")
         if not isinstance(self.stdout, bytes) or not isinstance(self.stderr, bytes):
             raise TypeError("step command streams must be bytes")
-        if type(self.stdout_truncated) is not bool or type(self.stderr_truncated) is not bool:
+        if (
+            type(self.stdout_truncated) is not bool
+            or type(self.stderr_truncated) is not bool
+        ):
             raise TypeError("step command truncation flags must be booleans")
 
     def __repr__(self) -> str:
@@ -113,18 +121,24 @@ def _validated_inputs(
     if inputs is None:
         return {}
     if not isinstance(inputs, Mapping):
-        raise StepCommandError("step command inputs must be a logical-reference mapping")
+        raise StepCommandError(
+            "step command inputs must be a logical-reference mapping"
+        )
     normalized: dict[str, pathlib.Path] = {}
     for logical_ref, path in inputs.items():
         if not isinstance(logical_ref, str) or not logical_ref:
-            raise StepCommandError("step command input references must be non-empty strings")
+            raise StepCommandError(
+                "step command input references must be non-empty strings"
+            )
         if not isinstance(path, pathlib.Path):
             path = pathlib.Path(path)
         try:
             resolved = path.resolve(strict=True)
             metadata = resolved.stat()
         except (OSError, RuntimeError) as exc:
-            raise StepCommandError("step command input artifact could not be opened") from exc
+            raise StepCommandError(
+                "step command input artifact could not be opened"
+            ) from exc
         if path_is_link_or_reparse(path) or not resolved.is_file() or not metadata:
             raise StepCommandError("step command input artifact must be a regular file")
         normalized[logical_ref] = resolved
@@ -155,7 +169,9 @@ def _substitute_argv(
                     )
                 rendered.append(str(inputs[logical_ref]))
             else:
-                raise StepCommandError(f"unknown step command placeholder in argument {index}")
+                raise StepCommandError(
+                    f"unknown step command placeholder in argument {index}"
+                )
             continue
 
         if _RECOGNIZED_TOKEN.search(argument):
@@ -178,12 +194,16 @@ def resolve_step_command_argv(
     try:
         root = pathlib.Path(repo_root).resolve(strict=True)
     except (OSError, RuntimeError) as exc:
-        raise StepCommandError("step command repository root could not be resolved") from exc
+        raise StepCommandError(
+            "step command repository root could not be resolved"
+        ) from exc
     if not root.is_dir():
         raise StepCommandError("step command repository root must be a directory")
     executable = python_executable or sys.executable
     if not isinstance(executable, str) or not executable or "\x00" in executable:
-        raise StepCommandError("step command Python interpreter must be a non-empty NUL-free string")
+        raise StepCommandError(
+            "step command Python interpreter must be a non-empty NUL-free string"
+        )
     return _substitute_argv(
         command,
         repo_root=root,
@@ -222,7 +242,9 @@ def _validate_utf8(result: StepCommandResult) -> None:
         try:
             stream.decode("utf-8")
         except UnicodeDecodeError as exc:
-            error = StepCommandEncodingError(f"step command emitted invalid UTF-8 on {name}")
+            error = StepCommandEncodingError(
+                f"step command emitted invalid UTF-8 on {name}"
+            )
             error._step_command_result = result
             raise error from exc
 
@@ -245,17 +267,27 @@ def run_step_command(
     their private ``_process_result`` attribute for the persistence helper.
     """
 
-    if isinstance(timeout_seconds, bool) or not isinstance(timeout_seconds, (int, float)):
+    if isinstance(timeout_seconds, bool) or not isinstance(
+        timeout_seconds, (int, float)
+    ):
         raise StepCommandError("step command timeout must be a finite positive number")
     if not math.isfinite(timeout_seconds) or timeout_seconds <= 0:
         raise StepCommandError("step command timeout must be a finite positive number")
-    if isinstance(max_output_bytes, bool) or not isinstance(max_output_bytes, int) or max_output_bytes < 0:
-        raise StepCommandError("step command output bound must be a non-negative integer")
+    if (
+        isinstance(max_output_bytes, bool)
+        or not isinstance(max_output_bytes, int)
+        or max_output_bytes < 0
+    ):
+        raise StepCommandError(
+            "step command output bound must be a non-negative integer"
+        )
 
     input_paths = _validated_inputs(inputs)
     if stdin is not None:
         if not isinstance(stdin, str) or stdin not in input_paths:
-            raise StepCommandError("step command stdin must exactly match a declared input")
+            raise StepCommandError(
+                "step command stdin must exactly match a declared input"
+            )
         input_path = input_paths[stdin]
     else:
         input_path = None
@@ -283,7 +315,9 @@ def run_step_command(
             )
             if truncated
         )
-        error = StepCommandTruncatedError(f"step command {streams} exceeded its capture limit")
+        error = StepCommandTruncatedError(
+            f"step command {streams} exceeded its capture limit"
+        )
         error._step_command_result = result
         raise error
     _validate_utf8(result)
@@ -307,7 +341,10 @@ def _assert_message(result: StepCommandResult) -> str:
     stderr = result.stderr.decode("utf-8", errors="surrogateescape")
     combined = "\n".join(part for part in (stderr.strip(), stdout.strip()) if part)
     safe = redact_diagnostic(combined, secrets=_environment_secrets())
-    return bounded_diagnostic(safe, max_chars=1_200) or f"command exited with status {result.returncode}"
+    return (
+        bounded_diagnostic(safe, max_chars=1_200)
+        or f"command exited with status {result.returncode}"
+    )
 
 
 def step_command_result_payload(
@@ -392,7 +429,9 @@ def execute_step_command(
     """
 
     if step.type not in {"exec", "assert"}:
-        raise StepCommandError("step command implementation requires an exec or assert step")
+        raise StepCommandError(
+            "step command implementation requires an exec or assert step"
+        )
     if isinstance(inputs, Mapping):
         input_map = dict(inputs)
         declared_references = set(step.inputs)
@@ -402,7 +441,9 @@ def execute_step_command(
             )
     else:
         if len(inputs) != len(step.inputs):
-            raise StepCommandError("step command input paths do not match declared inputs")
+            raise StepCommandError(
+                "step command input paths do not match declared inputs"
+            )
         input_map = dict(zip(step.inputs, inputs))
     store = artifacts or ArtifactStore(context.run_dir)
     store.prepare()
@@ -439,9 +480,13 @@ def execute_step_command(
         raise
 
     payload = step_command_result_payload(process_result, step_type=step.type)
-    persisted = _persist_process_result(store, state, step, process_result, payload=payload)
+    persisted = _persist_process_result(
+        store, state, step, process_result, payload=payload
+    )
     if step.type == "exec" and process_result.returncode != 0:
-        error = StepCommandExecutionError("step exec command returned a non-zero status")
+        error = StepCommandExecutionError(
+            "step exec command returned a non-zero status"
+        )
         error._step_command_result = process_result
         error._step_command_persisted = persisted
         raise error