agentevolve-optimizer 0.5.0__py3-none-any.whl

agent_evolve/infrastructure/stream_liveness.py

@@ -0,0 +1,383 @@
+"""Progress-aware, content-blind supervision for one provider stream.
+
+The supervisor knows nothing about prompts, model output, schemas, or benchmark
+semantics.  A provider adapter reports only closed progress kinds/channels.  A
+first-event deadline detects requests that never begin, an idle deadline moves
+forward whenever progress is observed, and an optional absolute deadline is a
+separate operational fail-safe.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable
+from contextlib import suppress
+import time
+from typing import Any, Protocol, TypeVar, runtime_checkable
+
+from agent_evolve.ports.structured_generator import (
+    GenerationFailureKind,
+    StructuredGenerationError,
+    StructuredStreamChannel,
+    StructuredStreamCleanupTimeoutError,
+    StructuredStreamLivenessPolicy,
+    StructuredStreamProgress,
+    StructuredStreamProgressKind,
+    StructuredStreamProgressSink,
+    StructuredStreamTimeoutError,
+    StructuredStreamTimeoutPhase,
+    StructuredStreamRetiredError,
+)
+
+
+ResultT = TypeVar("ResultT")
+
+
+@runtime_checkable
+class StreamProgressMarker(Protocol):
+    """Accept only a closed content identity, never a plaintext fragment.
+
+    Every successful operation must finish by marking exactly one
+    ``STREAM_COMPLETED`` event.  It must be the last mark and is emitted by the
+    adapter only after its framework call has returned a typed result.
+    """
+
+    def __call__(
+        self,
+        kind: StructuredStreamProgressKind,
+        channel: StructuredStreamChannel,
+        *,
+        event_content_utf8_bytes: int,
+        cumulative_content_utf8_bytes: int,
+        rolling_content_sha256: str,
+    ) -> None: ...
+
+
+StreamOperation = Callable[[StreamProgressMarker], Awaitable[ResultT]]
+StreamRetirementOperation = Callable[[], Awaitable[None]]
+
+
+@runtime_checkable
+class ContentBlindStreamSupervisor(Protocol):
+    """Injectable supervision port consumed by provider adapters."""
+
+    async def run(
+        self,
+        operation: StreamOperation[Any],
+        *,
+        call_id: str,
+        provider_attempt_id: str | None = None,
+        policy: StructuredStreamLivenessPolicy,
+        progress_sink: StructuredStreamProgressSink | None = None,
+    ) -> Any: ...
+
+
+class AsyncioContentBlindStreamSupervisor:
+    """Supervise one streamed operation without observing its content."""
+
+    def __init__(
+        self,
+        *,
+        monotonic_ns: Callable[[], int] = time.monotonic_ns,
+        retirement_operation: StreamRetirementOperation | None = None,
+    ) -> None:
+        if not callable(monotonic_ns):
+            raise TypeError("monotonic_ns must be callable")
+        if retirement_operation is not None and not callable(retirement_operation):
+            raise TypeError("retirement_operation must be callable or None")
+        self._monotonic_ns = monotonic_ns
+        self._retirement_operation = retirement_operation
+        self._retired = False
+
+    async def run(
+        self,
+        operation: StreamOperation[ResultT],
+        *,
+        call_id: str,
+        provider_attempt_id: str | None = None,
+        policy: StructuredStreamLivenessPolicy,
+        progress_sink: StructuredStreamProgressSink | None = None,
+    ) -> ResultT:
+        if not callable(operation):
+            raise TypeError("operation must be callable")
+        if self._retired:
+            raise StructuredStreamRetiredError()
+        if type(policy) is not StructuredStreamLivenessPolicy:
+            raise TypeError("policy must be a StructuredStreamLivenessPolicy")
+        policy.__post_init__()
+        if progress_sink is not None and not callable(progress_sink):
+            raise TypeError("progress_sink must be callable or None")
+
+        started_ns = self._monotonic_ns()
+        if type(started_ns) is not int or started_ns < 0:
+            raise ValueError("monotonic_ns returned an invalid value")
+        activity = asyncio.Event()
+        sequence = 0
+        first_event_ns: int | None = None
+        last_event_ns: int | None = None
+        last_cumulative_content_utf8_bytes = 0
+        last_kind: StructuredStreamProgressKind | None = None
+        stream_completed_count = 0
+        progress_accepting = True
+
+        def mark_progress(
+            kind: StructuredStreamProgressKind,
+            channel: StructuredStreamChannel,
+            *,
+            event_content_utf8_bytes: int,
+            cumulative_content_utf8_bytes: int,
+            rolling_content_sha256: str,
+        ) -> None:
+            nonlocal sequence, first_event_ns, last_event_ns, last_kind
+            nonlocal last_cumulative_content_utf8_bytes
+            nonlocal stream_completed_count
+            if not progress_accepting:
+                raise StructuredGenerationError(
+                    kind=GenerationFailureKind.CANCELLED,
+                    retryable=False,
+                    safe_message="stream progress occurred after liveness expiry",
+                )
+            if type(kind) is not StructuredStreamProgressKind:
+                raise TypeError("stream progress kind escaped the closed domain")
+            if type(channel) is not StructuredStreamChannel:
+                raise TypeError("stream channel escaped the closed domain")
+            if stream_completed_count:
+                raise StructuredGenerationError(
+                    kind=GenerationFailureKind.UNKNOWN,
+                    retryable=False,
+                    safe_message=(
+                        "stream progress occurred after local stream completion"
+                    ),
+                )
+            if (
+                type(event_content_utf8_bytes) is not int
+                or event_content_utf8_bytes < 0
+            ):
+                raise ValueError("stream event byte count escaped the closed domain")
+            if (
+                type(cumulative_content_utf8_bytes) is not int
+                or cumulative_content_utf8_bytes
+                != last_cumulative_content_utf8_bytes + event_content_utf8_bytes
+            ):
+                raise ValueError("stream cumulative byte count is not monotonic")
+            observed_ns = self._monotonic_ns()
+            if type(observed_ns) is not int or observed_ns < started_ns:
+                raise ValueError("monotonic stream observation moved backwards")
+            sequence += 1
+            if first_event_ns is None:
+                first_event_ns = observed_ns
+            last_event_ns = observed_ns
+            progress = StructuredStreamProgress(
+                call_id=call_id,
+                sequence=sequence,
+                kind=kind,
+                channel=channel,
+                elapsed_ns=observed_ns - started_ns,
+                event_content_utf8_bytes=event_content_utf8_bytes,
+                cumulative_content_utf8_bytes=cumulative_content_utf8_bytes,
+                rolling_content_sha256=rolling_content_sha256,
+                provider_attempt_id=provider_attempt_id,
+            )
+            if progress_sink is not None:
+                # Publication is deliberately fail closed: a scientific
+                # response cannot escape when required liveness evidence was
+                # not accepted by its injected sink.
+                progress_sink(progress)
+            last_cumulative_content_utf8_bytes = cumulative_content_utf8_bytes
+            last_kind = kind
+            if kind is StructuredStreamProgressKind.STREAM_COMPLETED:
+                stream_completed_count += 1
+            activity.set()
+
+        task = asyncio.create_task(operation(mark_progress))
+
+        async def expire_liveness(
+            phase: StructuredStreamTimeoutPhase,
+        ) -> None:
+            nonlocal progress_accepting
+            progress_accepting = False
+            settled = await _cancel_and_drain(
+                task,
+                timeout_ns=policy.cleanup_policy.cancel_drain_timeout_ns,
+            )
+            if settled:
+                raise StructuredStreamTimeoutError(phase)
+            # asyncio cannot kill a cancellation-resistant coroutine. Retire
+            # this supervisor before returning so neither a retry nor a later
+            # logical call can share the abandoned attempt's transport.
+            self._retired = True
+            await _retire_bounded(
+                self._retirement_operation,
+                timeout_ns=(
+                    policy.cleanup_policy.transport_retire_timeout_ns
+                ),
+            )
+            raise StructuredStreamCleanupTimeoutError(phase)
+
+        try:
+            while True:
+                if task.done():
+                    result = task.result()
+                    if (
+                        stream_completed_count != 1
+                        or last_kind is not StructuredStreamProgressKind.STREAM_COMPLETED
+                    ):
+                        raise StructuredGenerationError(
+                            kind=GenerationFailureKind.UNKNOWN,
+                            retryable=False,
+                            safe_message=(
+                                "streaming operation returned without one terminal "
+                                "local completion event"
+                            ),
+                        )
+                    return result
+
+                now_ns = self._monotonic_ns()
+                deadline_ns, phase = _next_deadline(
+                    started_ns=started_ns,
+                    first_event_ns=first_event_ns,
+                    last_event_ns=last_event_ns,
+                    policy=policy,
+                )
+                remaining_ns = deadline_ns - now_ns
+                if remaining_ns <= 0:
+                    await expire_liveness(phase)
+
+                observed_sequence = sequence
+                activity.clear()
+                if sequence != observed_sequence:
+                    continue
+                activity_waiter = asyncio.create_task(activity.wait())
+                try:
+                    done, _ = await asyncio.wait(
+                        (task, activity_waiter),
+                        timeout=remaining_ns / 1_000_000_000,
+                        return_when=asyncio.FIRST_COMPLETED,
+                    )
+                finally:
+                    if not activity_waiter.done():
+                        activity_waiter.cancel()
+                        with suppress(BaseException):
+                            await activity_waiter
+                if task in done:
+                    continue
+                if activity_waiter in done:
+                    continue
+                await expire_liveness(phase)
+        except asyncio.CancelledError:
+            progress_accepting = False
+            settled = await _cancel_and_drain(
+                task,
+                timeout_ns=policy.cleanup_policy.cancel_drain_timeout_ns,
+            )
+            if not settled:
+                self._retired = True
+                await _retire_bounded(
+                    self._retirement_operation,
+                    timeout_ns=(
+                        policy.cleanup_policy.transport_retire_timeout_ns
+                    ),
+                )
+            raise
+
+
+def _next_deadline(
+    *,
+    started_ns: int,
+    first_event_ns: int | None,
+    last_event_ns: int | None,
+    policy: StructuredStreamLivenessPolicy,
+) -> tuple[int, StructuredStreamTimeoutPhase]:
+    """Return the next boundary; absolute wins deterministic deadline ties."""
+
+    if first_event_ns is None:
+        candidates = [
+            (
+                started_ns + policy.first_event_timeout_ns,
+                1,
+                StructuredStreamTimeoutPhase.FIRST_EVENT,
+            )
+        ]
+    else:
+        assert last_event_ns is not None
+        candidates = [
+            (
+                last_event_ns + policy.idle_timeout_ns,
+                1,
+                StructuredStreamTimeoutPhase.IDLE,
+            )
+        ]
+    if policy.absolute_timeout_ns is not None:
+        candidates.append(
+            (
+                started_ns + policy.absolute_timeout_ns,
+                0,
+                StructuredStreamTimeoutPhase.ABSOLUTE,
+            )
+        )
+    deadline_ns, _, phase = min(candidates)
+    return deadline_ns, phase
+
+
+def _consume_terminal(task: "asyncio.Task[object]") -> None:
+    """Retrieve a detached task's terminal state without retaining content."""
+
+    with suppress(BaseException):
+        task.exception()
+
+
+async def _cancel_and_drain(
+    task: "asyncio.Task[object]",
+    *,
+    timeout_ns: int,
+) -> bool:
+    """Cancel one stream and wait at most the frozen cleanup interval."""
+
+    if type(timeout_ns) is not int or timeout_ns <= 0:
+        raise ValueError("timeout_ns must be a positive exact integer")
+    if not task.done():
+        task.cancel()
+    done, _ = await asyncio.wait(
+        (task,),
+        timeout=timeout_ns / 1_000_000_000,
+        return_when=asyncio.ALL_COMPLETED,
+    )
+    if task in done:
+        _consume_terminal(task)
+        return True
+    task.add_done_callback(_consume_terminal)
+    return False
+
+
+async def _retire_bounded(
+    retirement_operation: StreamRetirementOperation | None,
+    *,
+    timeout_ns: int,
+) -> bool:
+    """Invoke transport retirement without trusting close cancellation."""
+
+    if type(timeout_ns) is not int or timeout_ns <= 0:
+        raise ValueError("timeout_ns must be a positive exact integer")
+    if retirement_operation is None:
+        return True
+    task = asyncio.create_task(retirement_operation())
+    done, _ = await asyncio.wait(
+        (task,),
+        timeout=timeout_ns / 1_000_000_000,
+        return_when=asyncio.ALL_COMPLETED,
+    )
+    if task in done:
+        _consume_terminal(task)
+        return True
+    task.cancel()
+    task.add_done_callback(_consume_terminal)
+    return False
+
+
+__all__ = [
+    "AsyncioContentBlindStreamSupervisor",
+    "ContentBlindStreamSupervisor",
+    "StreamOperation",
+    "StreamProgressMarker",
+    "StreamRetirementOperation",
+]

agent_evolve/infrastructure/subprocess_boundary.py

@@ -0,0 +1,136 @@
+"""Deny-by-default subprocess implementation for the generic process port."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+import hashlib
+import json
+import math
+import os
+from pathlib import Path
+import stat
+import subprocess
+
+from agent_evolve.ports.subprocess_boundary import (
+    ChildProcessPolicy,
+    ChildProcessResult,
+)
+
+
+def _canonical_sha256(value: object) -> str:
+    payload = json.dumps(
+        value,
+        ensure_ascii=True,
+        allow_nan=False,
+        sort_keys=True,
+        separators=(",", ":"),
+    ).encode("ascii")
+    return hashlib.sha256(payload).hexdigest()
+
+
+class ExplicitEnvironmentSubprocessBoundary:
+    """Run bounded commands with exact argv, cwd, and allowlisted environment."""
+
+    def __init__(
+        self,
+        *,
+        policy: ChildProcessPolicy,
+        working_directory: Path,
+        source_environment: Mapping[str, str] | None = None,
+    ) -> None:
+        if type(policy) is not ChildProcessPolicy:
+            raise TypeError("policy must be exact ChildProcessPolicy")
+        if not isinstance(working_directory, Path) or not working_directory.is_absolute():
+            raise ValueError("working_directory must be an absolute pathlib.Path")
+        resolved_working_directory = working_directory.resolve(strict=True)
+        if not resolved_working_directory.is_dir():
+            raise ValueError("working_directory must resolve to a directory")
+        source = os.environ if source_environment is None else source_environment
+        environment: dict[str, str] = {}
+        for name in policy.inherited_environment_allowlist:
+            value = source.get(name)
+            if value is not None:
+                if type(value) is not str or "\x00" in value:
+                    raise ValueError("allowlisted environment values must be strings")
+                environment[name] = value
+        environment.update(dict(policy.fixed_environment))
+        self._policy = policy
+        self._working_directory = resolved_working_directory
+        self._environment = environment
+        self._record = {
+            "schema_version": 1,
+            "policy": {
+                **policy.to_record(),
+                "identity_sha256": policy.identity_sha256,
+            },
+            "working_directory": str(resolved_working_directory),
+            "effective_environment_names": sorted(environment),
+            "effective_environment_sha256": _canonical_sha256(environment),
+        }
+        self._identity_sha256 = _canonical_sha256(self._record)
+
+    @property
+    def identity_sha256(self) -> str:
+        return self._identity_sha256
+
+    def stable_record(self) -> dict[str, object]:
+        return {
+            **self._record,
+            "identity_sha256": self._identity_sha256,
+        }
+
+    def invocation_observation(self, executable: str) -> dict[str, object]:
+        if type(executable) is not str or not executable:
+            raise ValueError("executable must be a non-empty string")
+        invoked = Path(executable)
+        if not invoked.is_absolute():
+            raise ValueError("executable invocation path must be absolute")
+        metadata = invoked.lstat()
+        resolved = invoked.resolve(strict=True)
+        return {
+            "schema_version": 1,
+            "invoked_path": str(invoked),
+            "resolved_target": str(resolved),
+            "is_symlink": invoked.is_symlink(),
+            "lstat": {
+                "device": metadata.st_dev,
+                "inode": metadata.st_ino,
+                "mode_octal": oct(stat.S_IMODE(metadata.st_mode)),
+                "size_bytes": metadata.st_size,
+                "mtime_ns": metadata.st_mtime_ns,
+            },
+            "process_boundary_identity_sha256": self._identity_sha256,
+        }
+
+    def run(self, argv: tuple[str, ...], *, timeout_s: float) -> ChildProcessResult:
+        if (
+            type(argv) is not tuple
+            or not argv
+            or any(type(item) is not str or not item or "\x00" in item for item in argv)
+        ):
+            raise ValueError("argv must be a non-empty exact tuple of safe strings")
+        if (
+            isinstance(timeout_s, bool)
+            or not isinstance(timeout_s, (int, float))
+            or not math.isfinite(float(timeout_s))
+            or float(timeout_s) <= 0.0
+        ):
+            raise ValueError("timeout_s must be finite and positive")
+        completed = subprocess.run(
+            argv,
+            check=False,
+            capture_output=True,
+            text=True,
+            timeout=float(timeout_s),
+            cwd=self._working_directory,
+            env=dict(self._environment),
+            shell=False,
+        )
+        return ChildProcessResult(
+            returncode=completed.returncode,
+            stdout=completed.stdout,
+            stderr=completed.stderr,
+        )
+
+
+__all__ = ["ExplicitEnvironmentSubprocessBoundary"]

agent_evolve/integrations/__init__.py

@@ -0,0 +1 @@
+"""Concrete integrations (harness adapters). The core never imports from here."""

agent_evolve/integrations/botorch/__init__.py

@@ -0,0 +1,28 @@
+"""Optional direct and dependency-isolated BoTorch acquisition integrations."""
+
+from agent_evolve.integrations.botorch.subprocess_qlognehvi import (
+    FiniteAcquisitionSubprocessError,
+    IsolatedBotorchQLogNehviFiniteAcquisition,
+    build_isolated_botorch_qlognehvi,
+)
+
+
+def __getattr__(name: str) -> object:
+    # Keep torch and BoTorch optional in the main agent runtime.  The direct
+    # policy is imported only by users (and the isolated worker) that request it.
+    if name != "BotorchQLogNehviFiniteAcquisition":
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    from agent_evolve.integrations.botorch.finite_qlognehvi import (
+        BotorchQLogNehviFiniteAcquisition,
+    )
+
+    globals()[name] = BotorchQLogNehviFiniteAcquisition
+    return BotorchQLogNehviFiniteAcquisition
+
+
+__all__ = [
+    "BotorchQLogNehviFiniteAcquisition",
+    "FiniteAcquisitionSubprocessError",
+    "IsolatedBotorchQLogNehviFiniteAcquisition",
+    "build_isolated_botorch_qlognehvi",
+]