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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentic-runner
-Version: 2.6.1
+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.6.1 → 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.6.1 → 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.6.1"
+__version__ = "2.8.0"
 
 __all__ = ["__version__"]

{agentic_runner-2.6.1 → agentic_runner-2.8.0}/src/agentic_runner/activities.py

@@ -129,6 +129,14 @@ from agentic_runner.workers.fastapi_client import (
 )
 from agentic_runner.workers.harness_usage import extract_claude_result, extract_codex_turn_usage
 from agentic_runner.workers.mcp_config import McpServerEntry
+from agentic_runner.workers.skills import (
+    SkillDelivery,
+    delivery_for,
+    first_digest_mismatch,
+    remove_skills,
+    skills_preamble,
+    write_skills,
+)
 from agentic_runner_contracts.activity_io import (
     LEARNER_CHILDREN_BUDGET_BYTES,
     LEARNING_FAILED,
@@ -238,6 +246,7 @@ from agentic_runner_contracts.routing import (
 from agentic_runner_contracts.runtime_context import (
     EGRESS_ALLOW_LIST_KEY,
     McpServerSpec,
+    SkillVersionSpec,
     WorkerRuntimeContext,
     WorkerRuntimeContextResolver,
     work_branch_name,
@@ -491,6 +500,8 @@ class _RuntimeContextState:
     experience: str = ""
     experience_lesson_ids: tuple[str, ...] = ()
     experience_truncated: bool = False
+    # Console-v2 issue 28: the Skill versions attached to the Agent.
+    skills: tuple[SkillVersionSpec, ...] = ()
     workspace_path: Path | None = None
     branch_head_sha: str | None = None
     # The Autonomy Policy's tier source (PRD issue 14) -- see WorkerRuntimeContext for
@@ -533,6 +544,9 @@ class _DirectiveAttempt:
     # PRD issue 58: what config assembly wrote for the CLI, and where it may reach.
     mcp_servers: tuple[McpServerEntry, ...] | None = None
     egress_allow_list: tuple[str, ...] = ()
+    # Console-v2 issue 28: the attached Skills, for a runtime with no skills directory to
+    # write them into. Prefixed to the Directive prompt; empty when there is none.
+    skills_preamble: str = ""
 
     async def run_environment_hook(self) -> None:
         self.extra_env.update(await self.hooks.environment())
@@ -1325,6 +1339,7 @@ _ROUTING_EVIDENCE_SOURCE = "runner.routing"
 PRIOR_ATTEMPT_ALIVE_EVIDENCE_SOURCE = "runner.prior_attempt_alive"
 DIRECTIVE_TOKEN_EVIDENCE_SOURCE = "runner.directive_token"
 AGENT_RUNTIME_EVIDENCE_SOURCE = "runner.agent_runtime"
+SKILLS_EVIDENCE_SOURCE = "runner.skills"
 
 
 class _EvidenceWriter(Protocol):
@@ -1793,7 +1808,8 @@ class RunnerRalphActivities:
                     extra_env=attempt.env,
                     mcp_servers=attempt.mcp_servers,
                     egress_allow_list=attempt.egress_allow_list,
-                    prompt=_directive_prompt(
+                    prompt=attempt.skills_preamble
+                    + _directive_prompt(
                         completion_criteria=runtime_state.completion_criteria,
                         pr_body=request.pr_body,
                         persona_preamble=_persona_prompt_preamble(
@@ -2258,6 +2274,7 @@ class RunnerRalphActivities:
                 work_record_id, source=source, payload=dict(payload)
             )
 
+        await self._refuse_skill_digest_mismatch(work_record_id, state)
         credentials = await self._resolve_credentials(work_record_id, state)
         if credentials is not None:
             # Names only, at the moment they resolved (22 A1's Evidence): a support read
@@ -2321,6 +2338,13 @@ class RunnerRalphActivities:
                 credentials=credentials,
                 env=callback_env,
             )
+            delivered_preamble = await self._deliver_skills(
+                stack,
+                work_record_id=work_record_id,
+                state=state,
+                sandbox=sandbox,
+                directive_number=directive_number,
+            )
             session = await stack.enter_async_context(
                 DirectiveHookSession(
                     hooks=self._hooks,
@@ -2342,8 +2366,85 @@ class RunnerRalphActivities:
                 credentials=credentials,
                 mcp_servers=mcp_servers,
                 egress_allow_list=egress_allow_list,
+                skills_preamble=delivered_preamble,
             )
 
+    async def _refuse_skill_digest_mismatch(
+        self, work_record_id: str, state: _RuntimeContextState
+    ) -> None:
+        """A Skill whose body is not the version that was published fails the Directive
+        non-retryably (console-v2 issue 28): a retry would fetch the same body, and
+        running on it would hand the Agent prompt material no person reviewed."""
+
+        mismatch = first_digest_mismatch(state.skills)
+        if mismatch is None:
+            return
+        await _raise_recorded(
+            ApplicationError(
+                f"Skill {mismatch.slug} version {mismatch.version} does not match its sha256",
+                non_retryable=True,
+            ),
+            self._fastapi_client,
+            work_record_id,
+            source=SKILLS_EVIDENCE_SOURCE,
+            actor=self._actor(),
+            payload={
+                "event": "skills.digest_mismatch",
+                "agent_id": state.agent_id,
+                "slug": mismatch.slug,
+                "version": mismatch.version,
+                "sha256": mismatch.sha256,
+            },
+        )
+
+    async def _deliver_skills(
+        self,
+        stack: contextlib.AsyncExitStack,
+        *,
+        work_record_id: str,
+        state: _RuntimeContextState,
+        sandbox: DirectiveSandbox | None,
+        directive_number: int,
+    ) -> str:
+        """Put the attached Skills where this runtime reads them; return any preamble.
+
+        Written files are removed on the attempt's exit, success or failure. A Runner
+        with no Contract sandbox has no harness root it owns, so it falls back to the
+        preamble rather than writing into a shared ``CODEX_HOME``.
+        """
+
+        if not state.skills:
+            return ""
+        delivery = delivery_for(state.cli_kind)
+        if delivery is SkillDelivery.DIRECTORY and sandbox is None:
+            delivery = SkillDelivery.PROMPT_PREAMBLE
+        preamble = ""
+        if delivery is SkillDelivery.DIRECTORY:
+            assert sandbox is not None
+            # Registered before the write, so a write that fails half-way is cleaned too.
+            stack.push_async_callback(
+                remove_skills, sandbox.harness_config_dir, state.skills, uid=sandbox.uid
+            )
+            await write_skills(sandbox.harness_config_dir, state.skills, uid=sandbox.uid)
+        else:
+            preamble = skills_preamble(state.skills)
+        await self._fastapi_client.append_evidence(
+            work_record_id,
+            source=SKILLS_EVIDENCE_SOURCE,
+            payload={
+                "event": "skills.delivered",
+                "directive_number": directive_number,
+                "agent_id": state.agent_id,
+                "cli_kind": state.cli_kind,
+                "delivery": delivery.value,
+                "skills": [
+                    {"slug": skill.slug, "version": skill.version, "sha256": skill.sha256}
+                    for skill in state.skills
+                ],
+            },
+        )
+        return preamble
+
     async def _plan_mcp(
         self,
         work_record_id: str,
@@ -2995,6 +3096,7 @@ class RunnerRalphActivities:
             experience=runtime_context.experience,
             experience_lesson_ids=tuple(runtime_context.experience_lesson_ids),
             experience_truncated=runtime_context.experience_truncated,
+            skills=tuple(runtime_context.skills),
             workspace_path=resolved_workspace,
             branch_head_sha=branch_head_sha,
             product_id=runtime_context.product_id,
@@ -4253,7 +4355,8 @@ class RunnerRalphActivities:
                     extra_env=attempt.env,
                     mcp_servers=attempt.mcp_servers,
                     egress_allow_list=attempt.egress_allow_list,
-                    prompt=_learning_prompt(
+                    prompt=attempt.skills_preamble
+                    + _learning_prompt(
                         request,
                         base_branch=state.base_branch or request.base_ref,
                         transcript=self._learner_transcript(state, request.work_record_id),
@@ -4488,7 +4591,7 @@ class RunnerRalphActivities:
                     extra_env=attempt.env,
                     mcp_servers=attempt.mcp_servers,
                     egress_allow_list=attempt.egress_allow_list,
-                    prompt=await kind.prompt(state, prompt_notes),
+                    prompt=attempt.skills_preamble + await kind.prompt(state, prompt_notes),
                     base_branch=request.base_ref,
                     work_branch=state.work_branch,
                 )

{agentic_runner-2.6.1 → 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.6.1 → 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()