agentic-runner 2.7.0__tar.gz → 2.8.0__tar.gz

{agentic_runner-2.7.0 → agentic_runner-2.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentic-runner
-Version: 2.7.0
+Version: 2.8.0
 Summary: The Agentic OS Runner: an activity-only Temporal executor for workspaces, Agent Runtimes and verb seams
 License-Expression: AGPL-3.0-only
 License-File: LICENSE
@@ -12,6 +12,9 @@ Requires-Dist: pydantic-settings<3.0,>=2.0
 Requires-Dist: pydantic<3.0,>=2.0
 Requires-Dist: pyjwt[crypto]>=2.13.0
 Requires-Dist: temporalio<2.0,>=1.10
+Provides-Extra: testing
+Requires-Dist: pytest-asyncio<1.0,>=0.24; extra == 'testing'
+Requires-Dist: pytest<9.0,>=8.0; extra == 'testing'
 Description-Content-Type: text/markdown
 
 # agentic-runner

{agentic_runner-2.7.0 → agentic_runner-2.8.0}/pyproject.toml

@@ -19,9 +19,20 @@ dependencies = [
   "temporalio>=1.10,<2.0",
 ]
 
+[project.optional-dependencies]
+# The conformance kit (`agentic_runner.testing`, docs/conformance.md): the fake control
+# plane needs nothing beyond the dependencies above; the scenario suite needs these.
+testing = [
+  "pytest>=8.0,<9.0",
+  "pytest-asyncio>=0.24,<1.0",
+]
+
 [project.scripts]
 agentic-runner = "agentic_runner.cli:main"
 
+[project.entry-points.pytest11]
+agentic_runner = "agentic_runner.testing.plugin"
+
 [build-system]
 requires = ["hatchling>=1.27,<2.0"]
 build-backend = "hatchling.build"

{agentic_runner-2.7.0 → agentic_runner-2.8.0}/src/agentic_runner/__init__.py

@@ -7,6 +7,6 @@ stay on the platform; this package imports none of them, and a CI partition test
 (``tests/test_package_partition.py``) fails the build if that changes.
 """
 
-__version__ = "2.7.0"
+__version__ = "2.8.0"
 
 __all__ = ["__version__"]

{agentic_runner-2.7.0 → agentic_runner-2.8.0}/src/agentic_runner/registration.py

@@ -64,6 +64,10 @@ DIRECTIVE_TOKEN_PATH = "/api/runner/v1/runners/directive-token"
 INTAKE_WORK_RECORDS_PATH = "/api/runner/v1/runners/intake/work-records"
 INTAKE_IGNORED_PATH = "/api/runner/v1/runners/intake/ignored"
 
+# The refusal a revoked Runner's heartbeat earns (06 §2: revocation *is* the refused
+# heartbeat). The one reason this process stops on rather than retries.
+RUNNER_REVOKED_REASON = "runner_revoked"
+
 # What the state directory holds after a successful bootstrap. One file, mode 0600: the
 # private key is in it, and a Runner that loses it re-bootstraps rather than recovering.
 STATE_FILENAME = "runner-identity.json"

{agentic_runner-2.7.0 → agentic_runner-2.8.0}/src/agentic_runner/service.py

@@ -64,6 +64,7 @@ from agentic_runner.llm_proxy import CeilingStore, LlmProxy, SlotStore, UsageOut
 from agentic_runner.mcp import ToolServerHealthLog
 from agentic_runner.message_store import MESSAGES_DIR, MessageStore, TemporalWorkflowSignaller
 from agentic_runner.registration import (
+    RUNNER_REVOKED_REASON,
     RunnerRegistrationClient,
     RunnerRegistrationError,
     RunnerState,
@@ -890,6 +891,8 @@ async def _serve_registered(
             await link.exchange()
             break
         except Exception as error:  # noqa: BLE001 - keep trying until the control plane answers
+            if _revoked(error):
+                return 1
             _logger.warning("heartbeat failed before start: %s", error)
             if stop is not None and stop.is_set():
                 return 1
@@ -931,7 +934,11 @@ async def _serve_registered(
             graceful_shutdown_timeout=graceful_shutdown_timeout(settings),
             max_concurrent_activities=state.max_concurrent_directives,
         )
-        beat = asyncio.create_task(_heartbeat_forever(link, stream, client, interval))
+        stop = stop or asyncio.Event()
+        revoked = asyncio.Event()
+        beat = asyncio.create_task(
+            _heartbeat_forever(link, stream, client, interval, stop=stop, revoked=revoked)
+        )
         poll = asyncio.create_task(_poll_sources_forever(stream.sources, _source_poll_seconds()))
         readiness.ready = True
         await run_runner_lifecycle_hook(hooks, HookName.RUNNER_STARTUP)
@@ -945,7 +952,20 @@ async def _serve_registered(
                     await task
             await run_runner_lifecycle_hook(hooks, HookName.RUNNER_SHUTDOWN)
             await _report_stop(link, lifecycle)
-    return 0
+    return 1 if revoked.is_set() else 0
+
+
+def _revoked(error: Exception) -> bool:
+    """Whether a failed heartbeat was the control plane revoking this Runner.
+
+    Every other failure is a lost beat and the next tick retries it; a revocation is
+    final, so retrying would only dial a control plane that has already said no.
+    """
+
+    if isinstance(error, RunnerRegistrationError) and error.reason == RUNNER_REVOKED_REASON:
+        print(f"revoked by the control plane: {error}", flush=True)
+        return True
+    return False
 
 
 async def _report_stop(link: HeartbeatLink, lifecycle: LifecycleOutbox) -> None:
@@ -959,13 +979,20 @@ async def _report_stop(link: HeartbeatLink, lifecycle: LifecycleOutbox) -> None:
 
 
 async def _heartbeat_forever(
-    link: HeartbeatLink, stream: ControlPlaneStream, client: Client, interval: float
+    link: HeartbeatLink,
+    stream: ControlPlaneStream,
+    client: Client,
+    interval: float,
+    *,
+    stop: asyncio.Event,
+    revoked: asyncio.Event,
 ) -> None:
     """Every 30 s, for as long as the process lives; a missed beat is logged, not fatal.
 
     Staleness is the link's own property (issue 44): after three minutes of failures the
     verb seams refuse on their own, so there is nothing for this loop to do about a
-    failure except try again on the next tick.
+    failure except try again on the next tick. A revocation is the exception: it drains
+    the Worker exactly as SIGTERM would, and the process exits non-zero.
     """
 
     while True:
@@ -974,6 +1001,10 @@ async def _heartbeat_forever(
         try:
             await link.exchange()
         except Exception as error:  # noqa: BLE001 - any failed exchange is a lost beat
+            if _revoked(error):
+                revoked.set()
+                stop.set()
+                return
             _logger.warning("heartbeat failed: %s", error)
             continue
         if stream.runner_token is not None and stream.runner_token != token_before:

agentic_runner-2.8.0/src/agentic_runner/testing/__init__.py

@@ -0,0 +1,18 @@
+"""The Runner conformance kit (runner-repo issue 07, ``docs/conformance.md``).
+
+A fake control plane (:class:`FakeControlPlane`) and a scenario suite that proves a Runner
+build works without the platform: ``pip install 'agentic-runner[testing]'`` and then
+``pytest --pyargs agentic_runner.testing``. The fake itself needs only the Runner's own
+dependencies, so ``python -m agentic_runner.testing`` serves it from any Runner install,
+the image included; pytest and the scenario fixtures come with the extra.
+"""
+
+from agentic_runner.testing.control_plane import (
+    DEFAULT_NAMESPACE,
+    RUNNER_PREFIX,
+    Evidence,
+    FakeControlPlane,
+    Refusal,
+)
+
+__all__ = ["DEFAULT_NAMESPACE", "RUNNER_PREFIX", "Evidence", "FakeControlPlane", "Refusal"]

agentic_runner-2.8.0/src/agentic_runner/testing/__main__.py

@@ -0,0 +1,32 @@
+"""``python -m agentic_runner.testing [port]``: serve the fake control plane until killed.
+
+What the chart, Docker and workstation tests register a Runner against; ``GET /stats``
+reports what it saw.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from agentic_runner.testing.control_plane import DEFAULT_NAMESPACE, FakeControlPlane
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="python -m agentic_runner.testing")
+    parser.add_argument("port", type=int, nargs="?", default=8000)
+    parser.add_argument("--host", default="0.0.0.0")
+    parser.add_argument("--namespace", default=DEFAULT_NAMESPACE)
+    parser.add_argument("--host-party", default="organisation")
+    arguments = parser.parse_args()
+
+    plane = FakeControlPlane(namespace=arguments.namespace, host_party=arguments.host_party)
+    server = plane.server(arguments.host, arguments.port)
+    print(
+        f"fake control plane on :{server.server_address[1]}, namespace {arguments.namespace}",
+        flush=True,
+    )
+    server.serve_forever()
+
+
+if __name__ == "__main__":
+    main()

agentic_runner-2.8.0/src/agentic_runner/testing/control_plane.py

@@ -0,0 +1,441 @@
+"""The fake control plane: the Runner's side of the platform, answered the way it answers.
+
+One oracle for every test that needs a control plane (runner-repo issue 07): the unit
+tests mount it as an ``httpx.MockTransport``, the chart, Docker and workstation tests
+serve it over HTTP from the Runner's own install (``python -m agentic_runner.testing``),
+and the conformance scenarios do both. Standard library plus the Runner's own
+dependencies, so it runs anywhere a Runner does.
+
+It serves the public Runner surface only -- the ``/api/runner/v1`` prefix of issue 85
+(ADR-0016) -- and refuses anything else, so a Runner build that reaches for a platform
+route outside that surface fails here before it fails in production. What it checks is
+what the platform checks on that surface: the bootstrap body, the Ed25519 signature of
+every signed request against the identity it handed out, revocation, and the hosted
+queue. What it answers is the same shape the platform answers, refusals included
+(``{"detail": {"reason", "detail"}}``). Everything it saw is kept for the test to read,
+and ``GET /stats`` -- the one route outside the prefix, and the fake's own -- summarises
+it for a shell script.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import binascii
+import json
+import threading
+import time
+from collections.abc import Callable, Iterator, Mapping
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from datetime import UTC, datetime, timedelta
+from email.utils import formatdate
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from typing import Any
+from uuid import UUID, uuid4
+
+import httpx
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey, Ed25519PublicKey
+from pydantic import BaseModel, ValidationError
+
+from agentic_runner.registration import (
+    BOOTSTRAP_PATH,
+    DIRECTIVE_TOKEN_PATH,
+    HEARTBEAT_PATH,
+    RUNNER_REVOKED_REASON,
+)
+from agentic_runner_contracts import __version__ as contracts_version
+from agentic_runner_contracts.public_metadata import runner_task_queue
+from agentic_runner_contracts.runner_registration import (
+    BootstrapRequest,
+    BootstrapResponse,
+    DirectiveTokenRequest,
+    DirectiveTokenResponse,
+    FloorState,
+    HeartbeatAck,
+    HeartbeatEnvelope,
+    RunnerIdentityMaterial,
+)
+from agentic_runner_contracts.runner_signature import (
+    RUNNER_ID_HEADER,
+    SIGNATURE_HEADER,
+    SIGNED_AT_HEADER,
+    canonical_request,
+)
+
+__all__ = [
+    "DEFAULT_NAMESPACE",
+    "RUNNER_PREFIX",
+    "Evidence",
+    "FakeControlPlane",
+    "Refusal",
+]
+
+RUNNER_PREFIX = "/api/runner/v1"
+STATS_PATH = "/stats"
+# The namespace the chart, Docker and workstation tests start their Temporal dev server
+# with: one Organisation, whose id is the first non-nil UUID.
+DEFAULT_NAMESPACE = "org-00000000-0000-0000-0000-000000000001"
+_EVIDENCE_PATH_SUFFIX = "/evidence"
+_WORK_RECORDS_PATH = f"{RUNNER_PREFIX}/work-records/"
+_TOKEN_TTL = timedelta(hours=1)
+_DIRECTIVE_TOKEN_TTL = timedelta(minutes=15)
+
+
+@dataclass(frozen=True)
+class Evidence:
+    """One Evidence write as received; ``credential`` is ``directive`` or ``signed``."""
+
+    work_record_id: str
+    actor: str
+    source: str
+    payload: dict[str, Any]
+    credential: str
+
+
+@dataclass(frozen=True)
+class Refusal:
+    method: str
+    path: str
+    status: int
+    reason: str
+
+
+@dataclass(frozen=True)
+class _Answer:
+    status: int
+    body: dict[str, Any] | None = None
+
+
+class _RefusedError(Exception):
+    def __init__(self, status: int, reason: str, detail: str) -> None:
+        super().__init__(detail)
+        self.status = status
+        self.reason = reason
+
+
+@dataclass
+class _Registered:
+    public_key: Ed25519PublicKey
+    revoked: bool = False
+    tokens: int = 0
+
+
+@dataclass
+class FakeControlPlane:
+    """Bootstrap, heartbeat, Directive token and Evidence, answered the way the platform does.
+
+    ``heartbeat_interval_seconds`` is the cadence bootstrap hands out; a scenario that
+    waits on beats sets it low rather than waiting 30 s per beat.
+    """
+
+    namespace: str = DEFAULT_NAMESPACE
+    host_party: str = "organisation"
+    heartbeat_interval_seconds: int = 30
+    contracts_floor: str = contracts_version
+
+    bootstraps: list[BootstrapRequest] = field(default_factory=list)
+    runner_ids: list[UUID] = field(default_factory=list)
+    heartbeats: list[HeartbeatEnvelope] = field(default_factory=list)
+    heartbeat_runner_ids: list[UUID] = field(default_factory=list)
+    directive_tokens: list[str] = field(default_factory=list)
+    evidence: list[Evidence] = field(default_factory=list)
+    refusals: list[Refusal] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        self._lock = threading.Lock()
+        self._registered: dict[UUID, _Registered] = {}
+        self._minted: set[str] = set()
+
+    # ---------------------------------------------------------------- the test's levers
+
+    def revoke(self, runner_id: UUID) -> None:
+        """Revoke a Runner: from now on its signed requests are refused ``runner_revoked``."""
+
+        with self._lock:
+            self._registered[runner_id].revoked = True
+
+    async def wait_for(self, condition: Callable[[], bool], *, timeout: float = 10.0) -> None:
+        """Poll ``condition`` until it holds; works whether the fake is mounted or served."""
+
+        deadline = time.monotonic() + timeout
+        while not condition():
+            if time.monotonic() > deadline:
+                raise TimeoutError(f"fake control plane: condition not met in {timeout}s")
+            await asyncio.sleep(0.02)
+
+    def stats(self) -> dict[str, Any]:
+        with self._lock:
+            return {
+                "bootstraps": len(self.bootstraps),
+                "runner_ids": [str(runner_id) for runner_id in self.runner_ids],
+                "recipient_key_ids": sorted({b.recipient_key.key_id for b in self.bootstraps}),
+                "isolation_modes": sorted({b.isolation_mode.value for b in self.bootstraps}),
+                "heartbeats": len(self.heartbeats),
+                "heartbeat_runner_ids": sorted({str(r) for r in self.heartbeat_runner_ids}),
+                "directive_tokens": len(self.directive_tokens),
+                "evidence": len(self.evidence),
+                "refusals": [f"{r.method} {r.path} {r.status} {r.reason}" for r in self.refusals],
+            }
+
+    # ---------------------------------------------------------------- the two mounts
+
+    def transport(self) -> httpx.MockTransport:
+        """In-process: hand this to ``httpx.AsyncClient(transport=...)``."""
+
+        def handle(request: httpx.Request) -> httpx.Response:
+            answer = self.handle(
+                request.method,
+                request.url.raw_path.decode("ascii"),
+                request.headers,
+                request.content,
+            )
+            return httpx.Response(
+                answer.status,
+                json=answer.body,
+                headers={"date": formatdate(usegmt=True)},
+            )
+
+        return httpx.MockTransport(handle)
+
+    @contextmanager
+    def serving(self, host: str = "127.0.0.1", port: int = 0) -> Iterator[str]:
+        """Over HTTP, on a background thread; yields the base URL. Port 0 picks a free one."""
+
+        server = self.server(host, port)
+        thread = threading.Thread(target=server.serve_forever, daemon=True)
+        thread.start()
+        try:
+            yield f"http://{host}:{server.server_address[1]}"
+        finally:
+            server.shutdown()
+            server.server_close()
+            thread.join()
+
+    def server(self, host: str, port: int) -> ThreadingHTTPServer:
+        plane = self
+
+        class Handler(BaseHTTPRequestHandler):
+            def _answer(self) -> None:
+                length = int(self.headers.get("content-length", "0") or 0)
+                answer = plane.handle(
+                    self.command, self.path, dict(self.headers), self.rfile.read(length)
+                )
+                raw = b"" if answer.body is None else json.dumps(answer.body).encode()
+                # send_response adds the `Date` header the Runner's clock-skew reading uses.
+                self.send_response(answer.status)
+                self.send_header("content-type", "application/json")
+                self.send_header("content-length", str(len(raw)))
+                self.end_headers()
+                self.wfile.write(raw)
+
+            do_GET = _answer  # noqa: N815 - http.server's contract
+            do_POST = _answer  # noqa: N815 - http.server's contract
+            do_PUT = _answer  # noqa: N815 - http.server's contract
+            do_DELETE = _answer  # noqa: N815 - http.server's contract
+
+            def log_message(self, format: str, *args: Any) -> None:  # noqa: A002
+                print(f"fake control plane: {format % args}", flush=True)
+
+        return ThreadingHTTPServer((host, port), Handler)
+
+    # ---------------------------------------------------------------- the routes
+
+    def handle(self, method: str, target: str, headers: Mapping[str, str], body: bytes) -> _Answer:
+        """One request, as received: the raw target (query included) and the exact body."""
+
+        path = target.partition("?")[0]
+        if method == "GET" and path == STATS_PATH:
+            return _Answer(200, self.stats())
+        headers = {key.lower(): value for key, value in headers.items()}
+        try:
+            with self._lock:
+                return self._route(method, target, path, headers, body)
+        except _RefusedError as refused:
+            with self._lock:
+                self.refusals.append(Refusal(method, path, refused.status, refused.reason))
+            return _Answer(
+                refused.status, {"detail": {"reason": refused.reason, "detail": str(refused)}}
+            )
+
+    def _route(
+        self, method: str, target: str, path: str, headers: dict[str, str], body: bytes
+    ) -> _Answer:
+        if not path.startswith(f"{RUNNER_PREFIX}/"):
+            raise _RefusedError(
+                404,
+                "outside_runner_prefix",
+                f"{path} is not on the Runner surface ({RUNNER_PREFIX}); a Runner calls "
+                "nothing else",
+            )
+        if method == "POST" and path == BOOTSTRAP_PATH:
+            return self._bootstrap(body)
+        if method == "POST" and path == HEARTBEAT_PATH:
+            return self._heartbeat(method, target, headers, body)
+        if method == "POST" and path == DIRECTIVE_TOKEN_PATH:
+            return self._directive_token(method, target, headers, body)
+        if (
+            method == "POST"
+            and path.startswith(_WORK_RECORDS_PATH)
+            and path.endswith(_EVIDENCE_PATH_SUFFIX)
+        ):
+            work_record_id = path[len(_WORK_RECORDS_PATH) : -len(_EVIDENCE_PATH_SUFFIX)]
+            return self._evidence(work_record_id, method, target, headers, body)
+        raise _RefusedError(
+            404, "not_served", f"the fake control plane does not serve {method} {path}"
+        )
+
+    def _bootstrap(self, body: bytes) -> _Answer:
+        request = _parse(BootstrapRequest, body)
+        runner_id = uuid4()
+        key = Ed25519PrivateKey.generate()
+        self._registered[runner_id] = _Registered(public_key=key.public_key())
+        self.bootstraps.append(request)
+        self.runner_ids.append(runner_id)
+        print(f"bootstrap {runner_id} isolation={request.isolation_mode.value}", flush=True)
+        response = BootstrapResponse(
+            identity=RunnerIdentityMaterial(
+                runner_id=runner_id,
+                identity_id=f"identity-{runner_id}",
+                private_key_pem=key.private_bytes(
+                    serialization.Encoding.PEM,
+                    serialization.PrivateFormat.PKCS8,
+                    serialization.NoEncryption(),
+                ).decode("ascii"),
+            ),
+            temporal_namespace=self.namespace,
+            task_queue=runner_task_queue(runner_id),
+            runner_token=f"runner-token-{runner_id}-0",
+            runner_token_expires_at=datetime.now(UTC) + _TOKEN_TTL,
+            tag_set_version=1,
+            floor_state=FloorState.OK,
+            contracts_floor=self.contracts_floor,
+            host_party=self.host_party,
+            heartbeat_interval_seconds=self.heartbeat_interval_seconds,
+        )
+        return _Answer(200, response.model_dump(mode="json"))
+
+    def _heartbeat(self, method: str, target: str, headers: dict[str, str], body: bytes) -> _Answer:
+        runner_id, runner = self._signed(method, target, headers, body)
+        envelope = _parse(HeartbeatEnvelope, body)
+        expected = runner_task_queue(runner_id)
+        if envelope.hosted_task_queue != expected:
+            raise _RefusedError(
+                409,
+                "hosted_queue_mismatch",
+                f"Runner {runner_id} reports polling {envelope.hosted_task_queue!r}; "
+                f"Directives are dispatched to {expected!r}",
+            )
+        self.heartbeats.append(envelope)
+        self.heartbeat_runner_ids.append(runner_id)
+        runner.tokens += 1
+        ack = HeartbeatAck(
+            runner_id=runner_id,
+            runner_token=f"runner-token-{runner_id}-{runner.tokens}",
+            runner_token_expires_at=datetime.now(UTC) + _TOKEN_TTL,
+            floor_state=FloorState.OK,
+            contracts_floor=self.contracts_floor,
+            tag_set_version=envelope.tag_set_version,
+            accepts_new_directives=True,
+            # Every Usage Record committed, so the Runner's outbox drops exactly these.
+            usage_accepted=[f"{u.directive_id}:{u.sequence}" for u in envelope.usage],
+        )
+        return _Answer(200, ack.model_dump(mode="json"))
+
+    def _directive_token(
+        self, method: str, target: str, headers: dict[str, str], body: bytes
+    ) -> _Answer:
+        self._signed(method, target, headers, body)
+        request = _parse(DirectiveTokenRequest, body)
+        token = f"directive-token-{len(self.directive_tokens) + 1}"
+        self._minted.add(token)
+        self.directive_tokens.append(request.directive_id)
+        response = DirectiveTokenResponse(
+            directive_id=request.directive_id,
+            token=token,
+            expires_at=datetime.now(UTC) + _DIRECTIVE_TOKEN_TTL,
+        )
+        return _Answer(200, response.model_dump(mode="json"))
+
+    def _evidence(
+        self,
+        work_record_id: str,
+        method: str,
+        target: str,
+        headers: dict[str, str],
+        body: bytes,
+    ) -> _Answer:
+        # Either credential the platform accepts on this route: the Directive token the
+        # activity pulled, or -- before one exists -- the signed Runner envelope.
+        scheme, _, token = headers.get("authorization", "").partition(" ")
+        if scheme.lower() == "bearer" and token in self._minted:
+            credential = "directive"
+        else:
+            self._signed(method, target, headers, body)
+            credential = "signed"
+        try:
+            payload = json.loads(body)
+            entry = Evidence(
+                work_record_id=work_record_id,
+                actor=str(payload["actor"]),
+                source=str(payload["source"]),
+                payload=dict(payload["payload"]),
+                credential=credential,
+            )
+        except (ValueError, KeyError, TypeError) as error:
+            raise _RefusedError(
+                422, "evidence_invalid", f"not an Evidence write: {error}"
+            ) from None
+        self.evidence.append(entry)
+        return _Answer(
+            201,
+            {
+                "evidence_event_id": str(uuid4()),
+                "work_record_id": work_record_id,
+                "sequence": len(self.evidence),
+                "created": True,
+                "idempotency_key": payload.get("idempotency_key"),
+            },
+        )
+
+    def _signed(
+        self, method: str, target: str, headers: dict[str, str], body: bytes
+    ) -> tuple[UUID, _Registered]:
+        """The signed Runner envelope, checked the way the platform checks it (issue 71)."""
+
+        try:
+            runner_id = UUID(headers.get(RUNNER_ID_HEADER.lower(), ""))
+        except ValueError:
+            raise _RefusedError(
+                401, "signature_invalid", "no Runner id on a signed request"
+            ) from None
+        runner = self._registered.get(runner_id)
+        if runner is None:
+            raise _RefusedError(404, "runner_not_found", f"Runner {runner_id} not found")
+        try:
+            signature = base64.b64decode(headers.get(SIGNATURE_HEADER.lower(), ""), validate=True)
+            runner.public_key.verify(
+                signature,
+                canonical_request(
+                    method=method,
+                    path=target,
+                    signed_at=headers.get(SIGNED_AT_HEADER.lower(), ""),
+                    body=body,
+                ),
+            )
+        except (binascii.Error, InvalidSignature):
+            raise _RefusedError(
+                401, "signature_invalid", f"Runner {runner_id}: signature does not verify"
+            ) from None
+        if runner.revoked:
+            raise _RefusedError(403, RUNNER_REVOKED_REASON, f"Runner {runner_id} is revoked")
+        return runner_id, runner
+
+
+def _parse[Model: BaseModel](model: type[Model], body: bytes) -> Model:
+    try:
+        return model.model_validate_json(body)
+    except ValidationError as error:
+        raise _RefusedError(422, "request_invalid", str(error)) from None

agentic_runner-2.8.0/src/agentic_runner/testing/plugin.py

@@ -0,0 +1,178 @@
+"""The conformance kit's pytest plugin (``pytest11`` entry point ``agentic_runner``).
+
+Fixtures a fork's own tests can use as well as the scenarios in ``test_conformance.py``:
+``fake_control_plane`` serves :class:`FakeControlPlane` on a free port, and
+``runner_launcher`` starts the *installed* Runner -- ``agentic-runner run``, a real
+process -- against it, so a scenario sees exactly what an operator's process would do.
+
+Imports nothing beyond pytest and the Runner's own dependencies: the entry point loads
+this module into every pytest session of an environment that has the Runner installed,
+with or without the ``testing`` extra.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import shutil
+import signal
+import socket
+import subprocess
+import sys
+import time
+import urllib.error
+import urllib.request
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import pytest
+from temporalio.testing import WorkflowEnvironment
+
+from agentic_runner.testing.control_plane import DEFAULT_NAMESPACE, FakeControlPlane
+
+# A conformance Runner never runs a Directive that needs isolation or a credential, so it
+# runs `none`, unprivileged, with every path under the test's own directory.
+AGENT_TOKEN = "conformance-agent-token-0123456789"
+_RUN = "import sys; from agentic_runner.cli import main; sys.exit(main(['run']))"
+
+
+@dataclass(frozen=True)
+class ServedControlPlane:
+    plane: FakeControlPlane
+    url: str
+
+
+@dataclass
+class RunnerProcess:
+    """One ``agentic-runner run`` process; its stdout and stderr go to ``log``."""
+
+    process: subprocess.Popen[bytes]
+    log: Path
+    readiness_port: int
+
+    def ready(self) -> bool:
+        """The readiness probe the chart points Kubernetes at: registered, heard, polling."""
+
+        url = f"http://127.0.0.1:{self.readiness_port}/healthz"
+        try:
+            with urllib.request.urlopen(url, timeout=1) as response:
+                return bool(response.status == 200)
+        except (urllib.error.URLError, OSError):
+            return False
+
+    def output(self) -> str:
+        return self.log.read_text(encoding="utf-8", errors="replace")
+
+    def running(self) -> bool:
+        return self.process.poll() is None
+
+    def wait(self, timeout: float) -> int:
+        return self.process.wait(timeout=timeout)
+
+    def terminate(self, timeout: float = 60) -> int:
+        """SIGTERM -- what Kubernetes, ``docker stop`` and launchd send -- then wait."""
+
+        self.process.send_signal(signal.SIGTERM)
+        return self.wait(timeout)
+
+
+@dataclass
+class RunnerLauncher:
+    """Starts Runners that share one state directory, so a restart is the same Runner."""
+
+    root: Path
+    started: list[RunnerProcess] = field(default_factory=list)
+
+    def start(self, *, control_plane_url: str, temporal_address: str) -> RunnerProcess:
+        state = self.root / "state"
+        readiness_port = _free_port()
+        environment = {
+            **os.environ,
+            "AGENTIC_CONTROL_PLANE_URL": control_plane_url,
+            "AGENTIC_AGENT_TOKEN": AGENT_TOKEN,
+            "AGENTIC_RUNNER_ISOLATION": "none",
+            "AGENTIC_RUNNER_STATE_DIR": str(state),
+            "AGENTIC_RUNNER_WORKSPACE_ROOT": str(self.root / "workspaces"),
+            "AGENTIC_RUNNER_SOCKET_DIR": str(self.root / "sockets"),
+            "AGENTIC_RUNNER_CONFIG": str(self.root / "absent-config.toml"),
+            "AGENTIC_RUNNER_READINESS_PORT": str(readiness_port),
+            "TEMPORAL_ADDRESS": temporal_address,
+            "AGENTIC_TEMPORAL_TLS": "false",
+            "WORKSPACE_ROOT": str(self.root / "workspaces"),
+            "WORKER_STATE_DIR": str(state),
+            "CODEX_HOME": str(self.root / "codex"),
+        }
+        log = self.root / f"runner-{len(self.started)}.log"
+        with log.open("wb") as sink:
+            process = subprocess.Popen(
+                [sys.executable, "-c", _RUN],
+                env=environment,
+                stdout=sink,
+                stderr=subprocess.STDOUT,
+            )
+        runner = RunnerProcess(process=process, log=log, readiness_port=readiness_port)
+        self.started.append(runner)
+        return runner
+
+    def close(self) -> None:
+        for runner in self.started:
+            if runner.running():
+                runner.process.kill()
+                runner.process.wait()
+            print(f"--- {runner.log.name} (exit {runner.process.returncode})")
+            print(runner.output())
+
+
+async def start_temporal(namespace: str = DEFAULT_NAMESPACE) -> WorkflowEnvironment:
+    """A local Temporal dev server holding ``namespace``.
+
+    Uses a ``temporal`` CLI already on ``PATH`` when there is one; otherwise the SDK
+    downloads the dev server on first use.
+    """
+
+    return await WorkflowEnvironment.start_local(
+        namespace=namespace, dev_server_existing_path=shutil.which("temporal")
+    )
+
+
+async def until_ready(served: ServedControlPlane, runner: RunnerProcess, beats: int = 1) -> None:
+    """Wait until the Runner is ready and the fake has heard ``beats`` heartbeats.
+
+    Ready, not merely registered: the drain handler is installed once the Worker polls,
+    and a scenario that signals before then is testing start-up, not the drain. Fails at
+    once -- with the Runner's output -- if the process dies first.
+    """
+
+    plane = served.plane
+    deadline = time.monotonic() + 120
+    while len(plane.heartbeats) < beats or not runner.ready():
+        if not runner.running():
+            pytest.fail(f"the Runner exited {runner.process.returncode}:\n{runner.output()}")
+        if time.monotonic() > deadline:
+            pytest.fail(f"not ready in 120s; the fake saw {plane.stats()}:\n{runner.output()}")
+        await asyncio.sleep(0.1)
+
+
+def _free_port() -> int:
+    with socket.socket() as probe:
+        probe.bind(("127.0.0.1", 0))
+        return int(probe.getsockname()[1])
+
+
+@pytest.fixture
+def fake_control_plane() -> Iterator[ServedControlPlane]:
+    """The fake, served over HTTP, handing out a one-second heartbeat cadence."""
+
+    plane = FakeControlPlane(heartbeat_interval_seconds=1)
+    with plane.serving() as url:
+        yield ServedControlPlane(plane=plane, url=url)
+
+
+@pytest.fixture
+def runner_launcher(tmp_path: Path) -> Iterator[RunnerLauncher]:
+    launcher = RunnerLauncher(root=tmp_path)
+    try:
+        yield launcher
+    finally:
+        launcher.close()

agentic_runner-2.8.0/src/agentic_runner/testing/test_conformance.py

@@ -0,0 +1,163 @@
+"""The conformance scenarios: ``pytest --pyargs agentic_runner.testing``.
+
+Each one starts the installed Runner as a process against the fake control plane and a
+local Temporal dev server, and checks one thing an operator relies on: it registers once,
+it heartbeats signed, it runs a Directive dispatched to its own queue, it stops when
+revoked, and it drains on SIGTERM. A fork that passes these has a Runner the platform can
+drive; ``docs/conformance.md`` says what they do not cover.
+"""
+
+from __future__ import annotations
+
+from uuid import uuid4
+
+import pytest
+from temporalio.worker import Worker
+from temporalio.worker.workflow_sandbox import SandboxedWorkflowRunner, SandboxRestrictions
+
+from agentic_runner import __version__ as runner_version
+from agentic_runner.registration import RUNNER_REVOKED_REASON
+from agentic_runner.testing.plugin import (
+    RunnerLauncher,
+    ServedControlPlane,
+    start_temporal,
+    until_ready,
+)
+from agentic_runner.testing.workflow import RoundTripWorkflow
+from agentic_runner_contracts import __version__ as contracts_version
+from agentic_runner_contracts.activity_io import ContractResidueInput
+from agentic_runner_contracts.public_metadata import runner_task_queue
+from agentic_runner_contracts.routing import DirectiveRouting
+from agentic_runner_contracts.runner_registration import IsolationMode, LifecycleKind
+
+
+@pytest.mark.asyncio
+async def test_a_runner_registers_once_and_a_restart_is_the_same_runner(
+    fake_control_plane: ServedControlPlane, runner_launcher: RunnerLauncher
+) -> None:
+    plane = fake_control_plane.plane
+    async with await start_temporal(plane.namespace) as temporal:
+        address = temporal.client.service_client.config.target_host
+        first = runner_launcher.start(
+            control_plane_url=fake_control_plane.url, temporal_address=address
+        )
+        await until_ready(fake_control_plane, first)
+
+        [bootstrap] = plane.bootstraps
+        assert bootstrap.isolation_mode is IsolationMode.NONE
+        assert bootstrap.runner_version == runner_version
+        assert bootstrap.contracts_version == contracts_version
+        assert first.terminate() == 0
+
+        beats = len(plane.heartbeats)
+        second = runner_launcher.start(
+            control_plane_url=fake_control_plane.url, temporal_address=address
+        )
+        await until_ready(fake_control_plane, second, beats=beats + 1)
+        assert second.terminate() == 0
+
+    # The identity is read back from the state directory: no second registration.
+    assert len(plane.bootstraps) == 1
+    assert set(plane.heartbeat_runner_ids) == set(plane.runner_ids)
+
+
+@pytest.mark.asyncio
+async def test_a_runner_heartbeats_signed_from_its_own_queue(
+    fake_control_plane: ServedControlPlane, runner_launcher: RunnerLauncher
+) -> None:
+    plane = fake_control_plane.plane
+    async with await start_temporal(plane.namespace) as temporal:
+        runner = runner_launcher.start(
+            control_plane_url=fake_control_plane.url,
+            temporal_address=temporal.client.service_client.config.target_host,
+        )
+        await until_ready(fake_control_plane, runner, beats=3)
+        assert runner.terminate() == 0
+
+    [runner_id] = plane.runner_ids
+    assert set(plane.heartbeat_runner_ids) == {runner_id}
+    # Every beat verified against the identity the fake handed out; none was refused.
+    assert plane.refusals == []
+    assert {beat.hosted_task_queue for beat in plane.heartbeats} == {runner_task_queue(runner_id)}
+    assert {beat.contracts_version for beat in plane.heartbeats} == {contracts_version}
+
+
+@pytest.mark.asyncio
+async def test_a_directive_dispatched_to_the_runner_queue_comes_back_answered(
+    fake_control_plane: ServedControlPlane, runner_launcher: RunnerLauncher
+) -> None:
+    plane = fake_control_plane.plane
+    async with await start_temporal(plane.namespace) as temporal:
+        runner = runner_launcher.start(
+            control_plane_url=fake_control_plane.url,
+            temporal_address=temporal.client.service_client.config.target_host,
+        )
+        await until_ready(fake_control_plane, runner)
+        [runner_id] = plane.runner_ids
+        contract_id = str(uuid4())
+        request = ContractResidueInput(
+            contract_id=contract_id,
+            routing=DirectiveRouting(runner_id=str(runner_id), host_party=plane.host_party),
+        )
+
+        # The workflow is this suite's, not the platform's; the kit's own modules pass
+        # through the sandbox rather than being re-imported inside it.
+        async with Worker(
+            temporal.client,
+            task_queue="conformance-workflows",
+            workflows=[RoundTripWorkflow],
+            workflow_runner=SandboxedWorkflowRunner(
+                restrictions=SandboxRestrictions.default.with_passthrough_modules(
+                    "agentic_runner", "agentic_runner_contracts"
+                )
+            ),
+        ):
+            answer = await temporal.client.execute_workflow(
+                RoundTripWorkflow.run,
+                args=[runner_task_queue(runner_id), request],
+                id=f"conformance-{uuid4()}",
+                task_queue="conformance-workflows",
+            )
+        assert runner.terminate() == 0
+
+    assert answer.contract_id == contract_id
+    assert answer.workspaces_wiped == 0
+
+
+@pytest.mark.asyncio
+async def test_a_revoked_runner_stops(
+    fake_control_plane: ServedControlPlane, runner_launcher: RunnerLauncher
+) -> None:
+    plane = fake_control_plane.plane
+    async with await start_temporal(plane.namespace) as temporal:
+        runner = runner_launcher.start(
+            control_plane_url=fake_control_plane.url,
+            temporal_address=temporal.client.service_client.config.target_host,
+        )
+        await until_ready(fake_control_plane, runner)
+        [runner_id] = plane.runner_ids
+
+        plane.revoke(runner_id)
+        exit_code = runner.wait(timeout=60)
+
+    assert exit_code != 0
+    assert "revoked" in runner.output()
+    assert {refusal.reason for refusal in plane.refusals} == {RUNNER_REVOKED_REASON}
+
+
+@pytest.mark.asyncio
+async def test_sigterm_drains_to_a_clean_exit_and_reports_the_stop(
+    fake_control_plane: ServedControlPlane, runner_launcher: RunnerLauncher
+) -> None:
+    plane = fake_control_plane.plane
+    async with await start_temporal(plane.namespace) as temporal:
+        runner = runner_launcher.start(
+            control_plane_url=fake_control_plane.url,
+            temporal_address=temporal.client.service_client.config.target_host,
+        )
+        await until_ready(fake_control_plane, runner)
+
+        assert runner.terminate() == 0
+
+    # The last beat is the one the drain sends on its way out.
+    assert LifecycleKind.STOP in {event.kind for event in plane.heartbeats[-1].lifecycle}

agentic_runner-2.8.0/src/agentic_runner/testing/workflow.py

@@ -0,0 +1,37 @@
+"""The control plane's half of a Directive round trip, as small as one can be.
+
+The platform's workflows live in the platform; this one stands in for them in the
+conformance suite. It dispatches one Runner activity to ``runner.{runner_id}`` -- the
+queue a real workflow routes to -- and returns what the Runner answered. The activity is
+``wipe_contract_residue``: it touches no workspace, no Agent Runtime and no GitHub, so its
+answer depends only on the Runner having picked the task up off its own queue.
+"""
+
+from __future__ import annotations
+
+from datetime import timedelta
+
+from temporalio import workflow
+from temporalio.common import RetryPolicy
+
+with workflow.unsafe.imports_passed_through():
+    from agentic_runner_contracts.activity_io import ContractResidueInput, ContractResidueOutput
+
+ROUND_TRIP_ACTIVITY = "wipe_contract_residue"
+
+
+@workflow.defn(name="agentic_runner_conformance_round_trip")
+class RoundTripWorkflow:
+    @workflow.run
+    async def run(self, task_queue: str, request: ContractResidueInput) -> ContractResidueOutput:
+        answer: ContractResidueOutput = await workflow.execute_activity(
+            ROUND_TRIP_ACTIVITY,
+            request,
+            task_queue=task_queue,
+            result_type=ContractResidueOutput,
+            start_to_close_timeout=timedelta(seconds=30),
+            # One attempt: a Runner that cannot answer should fail the scenario, not
+            # retry it into the test's timeout.
+            retry_policy=RetryPolicy(maximum_attempts=1),
+        )
+        return answer