engineering-process 0.1.0__py3-none-any.whl

engineering_process/__init__.py

@@ -0,0 +1,3 @@
+"""Agent-neutral engineering process."""
+
+VERSION = "0.1.0"

engineering_process/_download_worker.py

@@ -0,0 +1,73 @@
+"""Private force-terminable HTTPS download worker."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+import sys
+import time
+
+from .contracts import ContractError, ManagedToolArtifact
+from .tooling import _download_artifact_direct, _validated_https_target
+
+
+_INPUT_LIMIT = 16_384
+
+
+def _payload() -> tuple[ManagedToolArtifact, Path, float]:
+    content = sys.stdin.buffer.read(_INPUT_LIMIT + 1)
+    if len(content) > _INPUT_LIMIT:
+        raise ContractError("download worker input exceeds its limit")
+    try:
+        value = json.loads(content.decode("ascii"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as error:
+        raise ContractError(f"download worker input is invalid: {error}") from error
+    if not isinstance(value, dict) or set(value) != {
+        "destination",
+        "maxDownloadBytes",
+        "timeoutSeconds",
+        "url",
+    }:
+        raise ContractError("download worker input has invalid fields")
+    url = value["url"]
+    maximum = value["maxDownloadBytes"]
+    timeout = value["timeoutSeconds"]
+    destination_value = value["destination"]
+    if not isinstance(url, str):
+        raise ContractError("download worker URL must be a string")
+    _validated_https_target(url, url)
+    if isinstance(maximum, bool) or not isinstance(maximum, int) or maximum < 1:
+        raise ContractError("download worker byte limit must be positive")
+    if isinstance(timeout, bool) or not isinstance(timeout, (int, float)) or timeout <= 0:
+        raise ContractError("download worker timeout must be positive")
+    if not isinstance(destination_value, str) or "\x00" in destination_value:
+        raise ContractError("download worker destination is invalid")
+    destination = Path(destination_value)
+    if not destination.is_absolute():
+        raise ContractError("download worker destination must be absolute")
+    artifact = ManagedToolArtifact(
+        platform="worker",
+        url=url,
+        checksum="sha256:" + "0" * 64,
+        archive_format="file",
+        strip_components=0,
+        max_download_bytes=maximum,
+        max_extracted_bytes=maximum,
+        max_files=1,
+        commands={},
+    )
+    return artifact, destination, time.monotonic() + float(timeout)
+
+
+def main() -> int:
+    try:
+        artifact, destination, deadline = _payload()
+        _download_artifact_direct(artifact, destination, deadline=deadline)
+        return 0
+    except Exception as error:
+        print(str(error), file=sys.stderr)
+        return 125
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

engineering_process/_supervisor_posix.py

@@ -0,0 +1,162 @@
+"""POSIX process-group backend for foreground-task supervision."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import signal
+import subprocess
+import time
+from typing import Mapping
+
+from .supervision import CleanupOutcome
+
+
+def _process_group_exists(process_group: int) -> bool:
+    try:
+        os.killpg(process_group, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    return True
+
+
+def _wait_for_process_group(process_group: int, timeout: float) -> bool:
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if not _process_group_exists(process_group):
+            return True
+        time.sleep(0.02)
+    return not _process_group_exists(process_group)
+
+
+def _terminate_group(process_group: int, grace_seconds: float) -> CleanupOutcome:
+    if not _process_group_exists(process_group):
+        return CleanupOutcome(bounded=True)
+    try:
+        os.killpg(process_group, signal.SIGTERM)
+    except ProcessLookupError:
+        return CleanupOutcome(bounded=True, descendants_found=True)
+    except OSError:
+        pass
+    if _wait_for_process_group(process_group, grace_seconds):
+        return CleanupOutcome(bounded=True, descendants_found=True)
+    try:
+        os.killpg(process_group, signal.SIGKILL)
+    except ProcessLookupError:
+        return CleanupOutcome(bounded=True, descendants_found=True)
+    except OSError:
+        pass
+    bounded = _wait_for_process_group(process_group, grace_seconds)
+    return CleanupOutcome(
+        bounded=bounded,
+        descendants_found=True,
+        error=(
+            None
+            if bounded
+            else "command process group could not be terminated within the bounded grace period"
+        ),
+    )
+
+
+class PosixProcessSupervisor:
+    def resolve_application(
+        self,
+        command: str,
+        *,
+        working_directory: Path,
+        environment: Mapping[str, str],
+    ) -> Path:
+        if not command or "\x00" in command:
+            raise OSError("command executable is invalid")
+        supplied = Path(command)
+        if supplied.is_absolute() or supplied.parent != Path("."):
+            candidate = supplied if supplied.is_absolute() else working_directory / supplied
+            try:
+                resolved = candidate.resolve(strict=True)
+            except OSError as error:
+                raise OSError(f"executable is unavailable: {command}") from error
+            if not resolved.is_file() or not os.access(resolved, os.X_OK):
+                raise OSError(f"executable is unavailable: {command}")
+            return resolved
+        for raw_directory in environment.get("PATH", "").split(os.pathsep):
+            directory = Path(raw_directory or ".")
+            if not directory.is_absolute():
+                directory = working_directory / directory
+            candidate = directory / command
+            try:
+                resolved = candidate.resolve(strict=True)
+            except OSError:
+                continue
+            if resolved.is_file() and os.access(resolved, os.X_OK):
+                return resolved
+        raise OSError(f"executable is unavailable: {command}")
+
+    def spawn(
+        self,
+        command: tuple[str, ...],
+        *,
+        working_directory: Path,
+        environment: Mapping[str, str],
+    ) -> subprocess.Popen[bytes]:
+        application = self.resolve_application(
+            command[0],
+            working_directory=working_directory,
+            environment=environment,
+        )
+        return subprocess.Popen(
+            command,
+            executable=application,
+            cwd=working_directory,
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            shell=False,
+            env=dict(environment),
+            start_new_session=True,
+        )
+
+    def terminate(
+        self,
+        process: subprocess.Popen[bytes],
+        *,
+        grace_seconds: float,
+    ) -> CleanupOutcome:
+        try:
+            os.killpg(process.pid, signal.SIGTERM)
+        except ProcessLookupError:
+            pass
+        except OSError:
+            pass
+        try:
+            process.wait(timeout=grace_seconds)
+        except subprocess.TimeoutExpired:
+            try:
+                os.killpg(process.pid, signal.SIGKILL)
+            except ProcessLookupError:
+                pass
+            except OSError:
+                pass
+            try:
+                process.wait(timeout=grace_seconds)
+            except subprocess.TimeoutExpired:
+                return CleanupOutcome(
+                    bounded=False,
+                    error="command root process survived bounded process-group termination",
+                )
+        descendants = _terminate_group(process.pid, grace_seconds)
+        return CleanupOutcome(bounded=descendants.bounded, error=descendants.error)
+
+    def finalize(
+        self,
+        process: subprocess.Popen[bytes],
+        *,
+        grace_seconds: float,
+    ) -> CleanupOutcome:
+        # The group id remains valid while any descendant from the owned session is
+        # alive, even after the original process has exited.
+        return _terminate_group(process.pid, grace_seconds)
+
+
+POSIX_SUPERVISOR = PosixProcessSupervisor()

engineering_process/_supervisor_windows.py

@@ -0,0 +1,148 @@
+"""Windows Job Object backend for foreground-task supervision."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import subprocess
+from typing import Mapping
+
+from .helper_launch import isolated_helper_command
+from .supervision import CleanupOutcome
+
+
+_UNSUPPORTED_SHELL_SUFFIXES = {".bat", ".cmd"}
+
+
+def resolve_windows_application(
+    command: str,
+    *,
+    working_directory: Path,
+    environment: Mapping[str, str],
+    path_separator: str | None = None,
+) -> Path:
+    """Resolve a native executable without CreateProcessW's CWD-first search.
+
+    Relative PATH entries are ignored.  A project executable is therefore selected
+    only when the command explicitly contains a path, never merely because a
+    same-named file exists in the checkout.
+    """
+
+    if not command or "\x00" in command:
+        raise OSError("command executable is invalid")
+    separator = os.pathsep if path_separator is None else path_separator
+    supplied = Path(command)
+    explicit_path = supplied.is_absolute() or supplied.parent != Path(".")
+    suffix = supplied.suffix.casefold()
+    if suffix in _UNSUPPORTED_SHELL_SUFFIXES:
+        raise OSError(
+            f"Windows batch command {command} requires a shell; only native .exe commands are supported"
+        )
+
+    candidates: list[Path] = []
+    names = (command,) if suffix else (f"{command}.exe",)
+    if explicit_path:
+        base = supplied if supplied.is_absolute() else working_directory / supplied
+        candidates.append(base if suffix else Path(f"{base}.exe"))
+    else:
+        for raw_directory in environment.get("PATH", "").split(separator):
+            if not raw_directory:
+                continue
+            directory = Path(raw_directory)
+            if not directory.is_absolute():
+                continue
+            candidates.extend(directory / name for name in names)
+
+    for candidate in candidates:
+        try:
+            resolved = candidate.resolve(strict=True)
+        except OSError:
+            continue
+        if resolved.is_file() and resolved.suffix.casefold() == ".exe":
+            return resolved
+    raise OSError(f"native Windows executable is unavailable: {command}")
+
+
+class WindowsProcessSupervisor:
+    def resolve_application(
+        self,
+        command: str,
+        *,
+        working_directory: Path,
+        environment: Mapping[str, str],
+    ) -> Path:
+        return resolve_windows_application(
+            command,
+            working_directory=working_directory,
+            environment=environment,
+        )
+
+    def spawn(
+        self,
+        command: tuple[str, ...],
+        *,
+        working_directory: Path,
+        environment: Mapping[str, str],
+    ) -> subprocess.Popen[bytes]:
+        application = self.resolve_application(
+            command[0],
+            working_directory=working_directory,
+            environment=environment,
+        )
+        wrapper = isolated_helper_command(
+            "engineering_process._windows_job",
+            "--application",
+            str(application),
+            "--",
+            *command,
+        )
+        return subprocess.Popen(
+            wrapper,
+            cwd=working_directory,
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            shell=False,
+            env=dict(environment),
+            creationflags=subprocess.CREATE_NEW_PROCESS_GROUP,
+        )
+
+    def terminate(
+        self,
+        process: subprocess.Popen[bytes],
+        *,
+        grace_seconds: float,
+    ) -> CleanupOutcome:
+        if process.poll() is not None:
+            return CleanupOutcome(bounded=True)
+        try:
+            process.terminate()
+            process.wait(timeout=grace_seconds)
+            return CleanupOutcome(bounded=True)
+        except (OSError, subprocess.TimeoutExpired):
+            try:
+                process.kill()
+            except OSError:
+                pass
+            try:
+                process.wait(timeout=grace_seconds)
+            except subprocess.TimeoutExpired:
+                return CleanupOutcome(
+                    bounded=False,
+                    error="Windows Job Object wrapper survived bounded termination",
+                )
+        return CleanupOutcome(bounded=True)
+
+    def finalize(
+        self,
+        process: subprocess.Popen[bytes],
+        *,
+        grace_seconds: float,
+    ) -> CleanupOutcome:
+        del process, grace_seconds
+        # The helper does not return until the target exits and its Job Object has
+        # no live descendants.  Cleanup failures are represented by its exit code.
+        return CleanupOutcome(bounded=True)
+
+
+WINDOWS_SUPERVISOR = WindowsProcessSupervisor()