agentevolve-optimizer 0.5.0__py3-none-any.whl

agent_evolve/infrastructure/authored_runtime.py

@@ -0,0 +1,188 @@
+"""Bounded execution for authored artifacts: one process per batch, typed outcomes.
+
+The optimizer never executes model-written source in its own process. Each
+batch of calls is shipped to ``authored_worker`` through the deny-by-default
+subprocess boundary -- exact argv, pinned cwd, no inherited environment --
+with a wall-clock timeout enforced here and CPU/memory rlimits applied inside
+the worker before the source is compiled. Every failure mode returns a
+:class:`RuntimeOutcome` with a typed status; nothing raises into the loop,
+because a crashing artifact is an ordinary, countable event, not an
+emergency.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Mapping, Optional, Sequence
+
+from agent_evolve.core.authored import AuthoredArtifact
+from agent_evolve.infrastructure.subprocess_boundary import (
+    ExplicitEnvironmentSubprocessBoundary,
+)
+from agent_evolve.ports.subprocess_boundary import ChildProcessPolicy
+
+__all__ = ["RuntimeLimits", "RuntimeOutcome", "AuthoredRuntime"]
+
+_DETAIL_LIMIT = 500
+
+#: Statuses the runtime can report. ``ok`` carries results; everything else
+#: carries a bounded detail string and empty results.
+STATUSES = ("ok", "unparseable", "forbidden_import", "crash", "timeout",
+            "memory", "bad_shape")
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimeLimits:
+    wall_time_s: float = 10.0
+    cpu_seconds: int = 8
+    memory_bytes: int = 512 * 1024 * 1024
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimeOutcome:
+    status: str
+    results: tuple = ()
+    detail: str = ""
+    #: Counters a harness-written prelude published inside the sandbox (see
+    #: ``policies/emit_scaffold.py``). Empty whenever no prelude ran or the
+    #: prelude wrote nothing serializable -- diagnostics, never results.
+    notes: Mapping[str, Any] = field(default_factory=dict)
+
+    @property
+    def ok(self) -> bool:
+        return self.status == "ok"
+
+
+class AuthoredRuntime:
+    """Runs authored artifacts out of process, one spawned worker per batch."""
+
+    def __init__(
+        self,
+        *,
+        limits: RuntimeLimits | None = None,
+        python_executable: str | None = None,
+    ) -> None:
+        self._limits = limits or RuntimeLimits()
+        self._python = python_executable or sys.executable
+        # The worker is launched BY PATH rather than as `-m agent_evolve...`.
+        # It imports nothing from this package (ast, json, sys, traceback and
+        # the interpreter), so the module form spent the whole of
+        # `agent_evolve.__init__` -- pydantic included -- on every batch:
+        # measured at 922ms per spawn against 21ms by path, which is 45x on
+        # every screen, every operator generation and every generated pool.
+        # The module form stays as a fallback for exotic installs (zipimport)
+        # where the source file is not on disk.
+        worker = Path(__file__).resolve().with_name("authored_worker.py")
+        self._worker = str(worker) if worker.is_file() else None
+        package_root = str(Path(__file__).resolve().parents[2])
+        self._policy = ChildProcessPolicy(
+            policy_id="authored_artifact_runtime",
+            policy_version=2,
+            inherited_environment_allowlist=(),
+            fixed_environment=(("PYTHONPATH", package_root),),
+        )
+
+    @property
+    def limits(self) -> RuntimeLimits:
+        return self._limits
+
+    def call(
+        self,
+        artifact: AuthoredArtifact,
+        calls: Sequence[Sequence[Any]],
+        *,
+        prelude: Optional[str] = None,
+        notes_global: Optional[str] = None,
+    ) -> RuntimeOutcome:
+        """Run *artifact* against every argument list in *calls*, bounded.
+
+        One process for the whole batch: a per-call process would pay the
+        interpreter startup once per candidate, and the batch is the unit the
+        loop actually needs (screen a pool, vary a generation's offspring).
+
+        *prelude* is HARNESS-written source executed into the artifact's
+        namespace before it -- machinery the caller would otherwise be asking
+        the model to re-derive, such as the emit scaffold that makes a
+        shape error impossible to construct. It is not import-gated, because
+        it is not the model's code; the artifact still is. *notes_global*
+        names a variable the prelude may leave counters in, returned as
+        :attr:`RuntimeOutcome.notes`.
+        """
+
+        if not calls:
+            return RuntimeOutcome(status="ok", results=())
+        with tempfile.TemporaryDirectory(prefix="agent_evolve_authored_") as scratch:
+            request_path = Path(scratch) / "request.json"
+            response_path = Path(scratch) / "response.json"
+            request = {
+                "schema_version": 1,
+                "entry_point": artifact.entry_point,
+                "source": artifact.source,
+                "limits": {
+                    "cpu_seconds": self._limits.cpu_seconds,
+                    "memory_bytes": self._limits.memory_bytes,
+                },
+                "calls": [list(call) for call in calls],
+            }
+            if prelude:
+                request["prelude"] = prelude
+                request["notes_global"] = notes_global or ""
+            request_path.write_text(json.dumps(request), encoding="utf-8")
+
+            boundary = ExplicitEnvironmentSubprocessBoundary(
+                policy=self._policy, working_directory=Path(scratch)
+            )
+            launch = ((self._worker,) if self._worker is not None
+                      else ("-m", "agent_evolve.infrastructure.authored_worker"))
+            argv = (self._python, *launch,
+                    str(request_path), str(response_path))
+            try:
+                result = boundary.run(argv, timeout_s=self._limits.wall_time_s)
+            except subprocess.TimeoutExpired:
+                return RuntimeOutcome(
+                    status="timeout",
+                    detail=f"wall limit {self._limits.wall_time_s}s",
+                )
+
+            if not response_path.exists():
+                if result.returncode != 0:
+                    return RuntimeOutcome(
+                        status="timeout" if result.returncode == -24 else "crash",
+                        detail=(f"rc {result.returncode}: "
+                                f"{result.stderr[-_DETAIL_LIMIT:]}"),
+                    )
+                return RuntimeOutcome(
+                    status="bad_shape", detail="worker wrote no response"
+                )
+            try:
+                payload = json.loads(response_path.read_text(encoding="utf-8"))
+            except (ValueError, OSError) as error:
+                return RuntimeOutcome(
+                    status="bad_shape",
+                    detail=f"unreadable response: {error}"[:_DETAIL_LIMIT],
+                )
+        status = payload.get("status")
+        if status not in STATUSES:
+            return RuntimeOutcome(
+                status="bad_shape", detail=f"unknown status {status!r}"
+            )
+        if status != "ok":
+            return RuntimeOutcome(
+                status=status, detail=str(payload.get("detail", ""))[:_DETAIL_LIMIT]
+            )
+        results = payload.get("results")
+        if not isinstance(results, list) or len(results) != len(calls):
+            return RuntimeOutcome(
+                status="bad_shape",
+                detail=(f"{len(results) if isinstance(results, list) else 'no'}"
+                        f" results for {len(calls)} calls"),
+            )
+        notes = payload.get("notes")
+        return RuntimeOutcome(
+            status="ok", results=tuple(results),
+            notes=dict(notes) if isinstance(notes, dict) else {})

agent_evolve/infrastructure/authored_worker.py

@@ -0,0 +1,171 @@
+"""Executes one authored artifact against a batch of calls, bounded.
+
+Runs OUT of the optimizer's process, one process per batch, launched by
+``AuthoredRuntime`` through the deny-by-default subprocess boundary. The
+threat model is untrusted-BUGGY code, not adversarial code: resource limits
+contain runaway loops and allocations, the import gate keeps an artifact from
+reaching the filesystem or network by accident, and every failure becomes a
+typed status the parent counts -- never an exception in the optimizer.
+
+Order of operations matters and is deliberate: the request is read first
+(this module's own imports must work unconstrained), THEN the resource
+limits are applied, THEN the source is gated and compiled. Authored code
+never runs a single instruction outside the limits.
+"""
+
+from __future__ import annotations
+
+import ast
+import json
+import sys
+import traceback
+
+#: Modules an authored artifact may import. Enough for arithmetic, statistics
+#: and seeded randomness; nothing that reaches the filesystem, the network,
+#: or another process.
+ALLOWED_IMPORTS = frozenset(
+    {"math", "statistics", "random", "json", "itertools", "collections",
+     "functools", "heapq", "bisect"}
+)
+
+_DETAIL_LIMIT = 500
+
+
+def _forbidden_import(source: str) -> str | None:
+    """The first disallowed root module the source imports, or ``None``."""
+
+    tree = ast.parse(source)
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                root = alias.name.split(".")[0]
+                if root not in ALLOWED_IMPORTS:
+                    return root
+        elif isinstance(node, ast.ImportFrom):
+            root = (node.module or "").split(".")[0]
+            if node.level or root not in ALLOWED_IMPORTS:
+                return root or "<relative>"
+        elif isinstance(node, ast.Name) and node.id == "__import__":
+            return "__import__"
+    return None
+
+
+def _apply_limits(limits: dict) -> None:
+    """Best-effort rlimits: containment for buggy code, not a security wall."""
+
+    try:
+        import resource
+    except ImportError:                      # non-POSIX: wall timeout remains
+        return
+    cpu = int(limits.get("cpu_seconds", 8))
+    memory = int(limits.get("memory_bytes", 512 * 1024 * 1024))
+    for kind, value in ((resource.RLIMIT_CPU, (cpu, cpu + 1)),
+                        (resource.RLIMIT_AS, (memory, memory))):
+        try:
+            resource.setrlimit(kind, value)
+        except (ValueError, OSError):
+            pass
+
+
+def _respond(path: str, payload: dict) -> None:
+    with open(path, "w", encoding="utf-8") as handle:
+        json.dump(payload, handle)
+
+
+def main(argv: list[str]) -> int:
+    request_path, response_path = argv
+    with open(request_path, encoding="utf-8") as handle:
+        request = json.load(handle)
+
+    _apply_limits(request.get("limits") or {})
+    source = request["source"]
+    entry_point = request["entry_point"]
+
+    try:
+        forbidden = _forbidden_import(source)
+    except SyntaxError as error:
+        _respond(response_path, {"status": "unparseable",
+                                 "detail": str(error)[:_DETAIL_LIMIT]})
+        return 0
+    if forbidden is not None:
+        _respond(response_path, {"status": "forbidden_import", "detail": forbidden})
+        return 0
+
+    namespace: dict = {"__name__": "authored_artifact"}
+    # A HARNESS-WRITTEN prelude, executed into the same namespace before the
+    # artifact and never gated: it is ours, not the model's, and it is how the
+    # caller hands authored code machinery it should not have to re-derive
+    # (see policies/emit_scaffold.py). Absent, nothing changes.
+    prelude = request.get("prelude")
+    if prelude:
+        try:
+            exec(compile(prelude, "<harness_prelude>", "exec"), namespace)  # noqa: S102
+        except Exception:
+            _respond(response_path, {
+                "status": "crash",
+                "detail": "harness prelude: "
+                          + traceback.format_exc()[-_DETAIL_LIMIT:],
+            })
+            return 0
+
+    try:
+        exec(compile(source, "<authored>", "exec"), namespace)  # noqa: S102
+    except SyntaxError as error:
+        _respond(response_path, {"status": "unparseable",
+                                 "detail": str(error)[:_DETAIL_LIMIT]})
+        return 0
+    except MemoryError:
+        _respond(response_path, {"status": "memory", "detail": "during exec"})
+        return 0
+    except Exception:
+        _respond(response_path, {"status": "crash",
+                                 "detail": traceback.format_exc()[-_DETAIL_LIMIT:]})
+        return 0
+
+    fn = namespace.get(entry_point)
+    if not callable(fn):
+        _respond(response_path, {
+            "status": "unparseable",
+            "detail": f"source defines no callable named {entry_point!r}",
+        })
+        return 0
+
+    results = []
+    try:
+        for call in request.get("calls", []):
+            results.append(fn(*call))
+    except MemoryError:
+        _respond(response_path, {"status": "memory",
+                                 "detail": f"after {len(results)} calls"})
+        return 0
+    except Exception:
+        _respond(response_path, {"status": "crash",
+                                 "detail": traceback.format_exc()[-_DETAIL_LIMIT:]})
+        return 0
+
+    payload = {"status": "ok", "results": results}
+    notes = request.get("notes_global")
+    if notes:
+        # The prelude's own counters, returned alongside the results. Only a
+        # JSON-serializable mapping crosses back, and a prelude that wrote
+        # something else costs the caller its diagnostics, never the batch.
+        value = namespace.get(notes)
+        if isinstance(value, dict):
+            try:
+                json.dumps(value)
+            except (TypeError, ValueError):
+                value = None
+            if value is not None:
+                payload["notes"] = value
+    try:
+        _respond(response_path, payload)
+    except (TypeError, ValueError):
+        _respond(response_path, {
+            "status": "bad_shape",
+            "detail": "results are not JSON-serializable",
+        })
+    return 0
+
+
+if __name__ == "__main__":                        # pragma: no cover
+    raise SystemExit(main(sys.argv[1:]))

agent_evolve/infrastructure/clock.py

@@ -0,0 +1,53 @@
+"""System and deterministic clock implementations."""
+
+from __future__ import annotations
+
+import threading
+import time
+from datetime import datetime, timedelta, timezone
+
+
+class SystemClock:
+    def utc_now(self) -> datetime:
+        return datetime.now(timezone.utc)
+
+    def monotonic_ns(self) -> int:
+        return time.monotonic_ns()
+
+
+class FakeClock:
+    """Manually advanced clock; reads have no hidden side effects."""
+
+    def __init__(
+        self,
+        start_utc: datetime | None = None,
+        *,
+        start_monotonic_ns: int = 0,
+    ) -> None:
+        start_utc = start_utc or datetime(2000, 1, 1, tzinfo=timezone.utc)
+        if start_utc.utcoffset() != timedelta(0):
+            raise ValueError("start_utc must be timezone-aware UTC")
+        if (
+            isinstance(start_monotonic_ns, bool)
+            or not isinstance(start_monotonic_ns, int)
+            or start_monotonic_ns < 0
+        ):
+            raise ValueError("start_monotonic_ns must be a non-negative integer")
+        self._utc = start_utc
+        self._monotonic_ns = start_monotonic_ns
+        self._lock = threading.Lock()
+
+    def utc_now(self) -> datetime:
+        with self._lock:
+            return self._utc
+
+    def monotonic_ns(self) -> int:
+        with self._lock:
+            return self._monotonic_ns
+
+    def advance_ns(self, nanoseconds: int) -> None:
+        if isinstance(nanoseconds, bool) or not isinstance(nanoseconds, int) or nanoseconds < 0:
+            raise ValueError("nanoseconds must be a non-negative integer")
+        with self._lock:
+            self._monotonic_ns += nanoseconds
+            self._utc += timedelta(microseconds=nanoseconds / 1_000)

agent_evolve/infrastructure/events/__init__.py

@@ -0,0 +1,6 @@
+"""Append-only event-store implementations."""
+
+from agent_evolve.infrastructure.events.in_memory import InMemoryEventStore
+from agent_evolve.infrastructure.events.jsonl import JsonlEventStore
+
+__all__ = ["InMemoryEventStore", "JsonlEventStore"]

agent_evolve/infrastructure/events/_validation.py

@@ -0,0 +1,89 @@
+"""Shared validation for EventStore implementations."""
+
+from __future__ import annotations
+
+from typing import AbstractSet, Sequence
+
+from agent_evolve.domain.event import EventEnvelope, validated_event_snapshot
+from agent_evolve.domain.ids import EventId, RunId
+from agent_evolve.ports.event_store import (
+    DuplicateEventIdError,
+    EventCausationError,
+    EventRunMismatchError,
+    EventSequenceError,
+    OptimisticConcurrencyError,
+)
+
+
+def prepare_event_for_append(event: EventEnvelope) -> EventEnvelope:
+    """Detach and fully revalidate a caller-owned event before persistence."""
+
+    return validated_event_snapshot(event)
+
+
+def validate_append(
+    existing: Sequence[EventEnvelope],
+    event: EventEnvelope,
+    *,
+    expected_previous_sequence: int,
+    known_event_ids: AbstractSet[EventId],
+) -> None:
+    if (
+        type(expected_previous_sequence) is not int
+        or expected_previous_sequence < 0
+    ):
+        raise EventSequenceError("expected_previous_sequence must be non-negative")
+
+    current_sequence = existing[-1].sequence_number if existing else 0
+    if expected_previous_sequence != current_sequence:
+        raise OptimisticConcurrencyError(
+            f"Expected previous sequence {expected_previous_sequence}, "
+            f"but run is at {current_sequence}"
+        )
+    if event.sequence_number != current_sequence + 1:
+        raise EventSequenceError(
+            f"Event sequence must be {current_sequence + 1}, got {event.sequence_number}"
+        )
+    if existing and event.run_id != existing[0].run_id:
+        raise EventRunMismatchError(
+            f"Event run {event.run_id} does not match stream {existing[0].run_id}"
+        )
+    if event.event_id in known_event_ids:
+        raise DuplicateEventIdError(f"Duplicate event ID {event.event_id}")
+    if event.causation_event_id is not None and all(
+        prior.event_id != event.causation_event_id for prior in existing
+    ):
+        raise EventCausationError(
+            f"Causation event {event.causation_event_id} must precede the event "
+            f"in the same run {event.run_id}"
+        )
+    if existing and event.monotonic_offset_ns < existing[-1].monotonic_offset_ns:
+        raise EventSequenceError("monotonic_offset_ns cannot decrease within a run")
+
+
+def validate_loaded_stream(run_id: RunId, events: Sequence[EventEnvelope]) -> None:
+    previous_sequence = 0
+    previous_offset = 0
+    ids = set()
+    for event in events:
+        if event.run_id != run_id:
+            raise EventRunMismatchError(
+                f"Event run {event.run_id} does not match stream {run_id}"
+            )
+        if event.sequence_number != previous_sequence + 1:
+            raise EventSequenceError(
+                f"Non-contiguous event sequence for {run_id}: "
+                f"expected {previous_sequence + 1}, got {event.sequence_number}"
+            )
+        if event.event_id in ids:
+            raise DuplicateEventIdError(f"Duplicate event ID {event.event_id}")
+        if event.causation_event_id is not None and event.causation_event_id not in ids:
+            raise EventCausationError(
+                f"Causation event {event.causation_event_id} must precede the event "
+                f"in the same run {run_id}"
+            )
+        if previous_sequence and event.monotonic_offset_ns < previous_offset:
+            raise EventSequenceError("monotonic_offset_ns cannot decrease within a run")
+        ids.add(event.event_id)
+        previous_sequence = event.sequence_number
+        previous_offset = event.monotonic_offset_ns

agent_evolve/infrastructure/events/in_memory.py

@@ -0,0 +1,56 @@
+"""Thread-safe in-memory EventStore, primarily for tests and ephemeral runs."""
+
+from __future__ import annotations
+
+import threading
+from typing import Dict, List, Tuple
+
+from agent_evolve.domain.event import EventEnvelope, validated_event_snapshot
+from agent_evolve.domain.ids import EventId, RunId
+from agent_evolve.infrastructure.events._validation import (
+    prepare_event_for_append,
+    validate_append,
+)
+
+
+class InMemoryEventStore:
+    def __init__(self) -> None:
+        self._events: Dict[RunId, List[EventEnvelope]] = {}
+        self._event_ids: set[EventId] = set()
+        self._lock = threading.RLock()
+
+    def append(
+        self,
+        event: EventEnvelope,
+        *,
+        expected_previous_sequence: int,
+    ) -> None:
+        snapshot = prepare_event_for_append(event)
+        with self._lock:
+            stream = self._events.setdefault(snapshot.run_id, [])
+            validate_append(
+                stream,
+                snapshot,
+                expected_previous_sequence=expected_previous_sequence,
+                known_event_ids=self._event_ids,
+            )
+            stream.append(snapshot)
+            self._event_ids.add(snapshot.event_id)
+
+    def read(
+        self,
+        run_id: RunId,
+        *,
+        after_sequence: int = 0,
+    ) -> Tuple[EventEnvelope, ...]:
+        if type(after_sequence) is not int or after_sequence < 0:
+            raise ValueError("after_sequence must be a non-negative integer")
+        if type(run_id) is not RunId:
+            raise TypeError("run_id must be an exact RunId")
+        canonical_run_id = RunId(run_id.value)
+        with self._lock:
+            return tuple(
+                validated_event_snapshot(event)
+                for event in self._events.get(canonical_run_id, ())
+                if event.sequence_number > after_sequence
+            )