agentic-runner 3.21.0__tar.gz → 3.22.0__tar.gz

{agentic_runner-3.21.0 → agentic_runner-3.22.0}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.5
 Name: agentic-runner
-Version: 3.21.0
+Version: 3.22.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
 Requires-Python: >=3.12
-Requires-Dist: agentic-runner-contracts==3.21.0
+Requires-Dist: agentic-runner-contracts==3.22.0
 Requires-Dist: cryptography<51,>=50
 Requires-Dist: httpx<1.0,>=0.27
 Requires-Dist: pydantic-settings<3.0,>=2.0

{agentic_runner-3.21.0 → agentic_runner-3.22.0}/pyproject.toml

@@ -10,7 +10,7 @@ dependencies = [
   # Exactly this release's contracts: the two ship as one version, and an unpinned
   # requirement let `uv tool upgrade` keep an older contracts wheel the Runner cannot
   # import from (QTS-1473). `scripts/set-version.py` moves it with the version.
-  "agentic-runner-contracts==3.21.0",
+  "agentic-runner-contracts==3.22.0",
   # Imported directly by `registration.py` (the Ed25519 identity that signs every
   # heartbeat); already present transitively through pyjwt[crypto], declared because
   # we import it.

{agentic_runner-3.21.0 → agentic_runner-3.22.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__ = "3.21.0"
+__version__ = "3.22.0"
 
 __all__ = ["__version__"]

{agentic_runner-3.21.0 → agentic_runner-3.22.0}/src/agentic_runner/activities.py

@@ -77,7 +77,14 @@ from agentic_runner.credentials import (
     EmptyCredentialStore,
     UnresolvableCredentialReferenceError,
 )
-from agentic_runner.egress import EGRESS_REFUSED_SOURCE, EgressProxy, Resolver, host_of
+from agentic_runner.egress import (
+    EGRESS_REFUSED_SOURCE,
+    EgressProxy,
+    Resolver,
+    destination_denied,
+    host_of,
+    url_destination,
+)
 from agentic_runner.harness_self_test import DirectivesInFlight
 from agentic_runner.heartbeat_link import HeartbeatLink, SeamUnavailableError
 from agentic_runner.hooks import (
@@ -119,6 +126,11 @@ from agentic_runner.mcp import (
 )
 from agentic_runner.message_store import MessageStore, WorkflowSignaller
 from agentic_runner.registration import RunnerRegistrationError
+from agentic_runner.runner_limit import (
+    EMPTY_RUNNER_LIMIT,
+    RUNNER_LIMIT_EVIDENCE_SOURCE,
+    AppliedRunnerLimit,
+)
 from agentic_runner.runtime import verifier_command
 from agentic_runner.runtime.verifier_command import CommandValidationError
 from agentic_runner.usage_windows import UsageWindows
@@ -261,6 +273,7 @@ from agentic_runner_contracts.grants import (
     REPO_RESOURCE_TYPE,
     UNENFORCED_SNAPSHOT,
     Decision,
+    GrantLink,
     GrantSnapshot,
 )
 from agentic_runner_contracts.grants.seam import VerbDecision, decide_verb
@@ -340,6 +353,8 @@ _CRITIC_VETO_SOURCE = "critic.veto"
 # lets the Directive write; the Runner reads it and deletes it before anything else runs.
 _LEARNING_RUN_SOURCE = "learning.directive_run"
 _LESSONS_FILE = Path(".agentic-learner") / "lessons.json"
+# The `ending_kind` agentic-os sends for the leaving Assignee's Learning Directive.
+_LEARNING_ENDING_HANDOFF = "HANDOFF"
 # PRD issue 59: where a Lead's Directive writes its plan (children to open, children to
 # end, whether it ends the Epic). Read and deleted before anything is committed, so the
 # plan never lands on the branch; the control plane evaluates `work.open` / `work.end`.
@@ -1090,10 +1105,19 @@ def _learning_prompt(request: LearningDirectiveInput, *, base_branch: str, trans
     transcript_section = section("Conversation transcript", transcript or "(none)")
     lessons_section = section("Existing Lessons", request.existing_lessons or "(none)")
     cut_line = f"Cut to fit: {'; '.join(notes)}.\n\n" if notes else ""
-    return (
-        "You are the Learner. This Work Record has ended "
+    # A hand-off is no ending: the work goes on under the next Assignee, and the Evidence
+    # the platform sent is the leaving Agent's own Directives only (QTS-1566, QTS-1574).
+    occasion = (
+        "The Agent whose work you review handed this Work Record off and is no longer its "
+        "Assignee; the work goes on without it. Propose Lessons from its own part of the work "
+        "that a future Directive of the same Persona should know"
+        if request.ending_kind == _LEARNING_ENDING_HANDOFF
+        else "This Work Record has ended "
         f"({request.ending_kind}{' / ' + request.end_reason if request.end_reason else ''}). "
-        "Propose Lessons a future Directive of the same Persona should know -- from a "
+        "Propose Lessons a future Directive of the same Persona should know"
+    )
+    return (
+        f"You are the Learner. {occasion} -- from a "
         "failure as much as from a success. Propose nothing rather than something vague, "
         "and never repeat an existing Lesson below.\n\n"
         f"The change is the branch checked out here: read it with `git diff "
@@ -1688,8 +1712,12 @@ class RunnerRalphActivities:
         attempt_records: AttemptRecords | None = None,
         directives_in_flight: DirectivesInFlight | None = None,
         usage_windows: UsageWindows | None = None,
+        runner_limit: AppliedRunnerLimit | None = None,
     ) -> None:
         self._fastapi_client = fastapi_client
+        # What this Runner's host denies every Agent on it, checked at start (ADR-0022
+        # §52-§55). Empty by default, which narrows nothing.
+        self._runner_limit = runner_limit or EMPTY_RUNNER_LIMIT
         # Read by the harness self-test, which never runs beside a Contract's Directive.
         self._directives_in_flight = directives_in_flight or DirectivesInFlight()
         # Local-agents 10: None off a user-hosted Runner, which reports no usage windows.
@@ -2850,6 +2878,7 @@ class RunnerRalphActivities:
             state.mcp_servers,
             consented=consented,
             declined=declined,
+            runner_limit=self._runner_limit.tools_grant,
         )
         granted = list(plan.granted)
         withheld = list(plan.withheld)
@@ -2904,7 +2933,8 @@ class RunnerRalphActivities:
         proxy variables.
         """
 
-        needs_token = bool(state.egress_allow_list) or any(
+        denied_networks = self._runner_limit.networks
+        needs_token = bool(state.egress_allow_list or denied_networks) or any(
             spec.credential_reference is not None for spec, _ in plan.granted
         )
         if needs_token and CALLBACK_TOKEN_ENV not in env:
@@ -2936,6 +2966,7 @@ class RunnerRalphActivities:
             )
             entries.append(entry_for(spec, hosted_url=hosted.url, bearer_env=CALLBACK_TOKEN_ENV))
 
+        await self._refuse_denied_destinations(work_record_id, state, entries, env)
         allow_list: tuple[str, ...] = ()
         if state.egress_allow_list:
             allow_list = tuple(
@@ -2959,17 +2990,27 @@ class RunnerRalphActivities:
                 )
             )
 
-            async def refused(host: str, port: int) -> None:
+        if state.egress_allow_list or denied_networks:
+
+            async def refused(host: str, port: int, limit_entry: int | None) -> None:
+                payload: dict[str, object] = {"event": "egress.refused", "host": host, "port": port}
+                if limit_entry is not None:
+                    payload.update(
+                        deciding_link=GrantLink.RUNNER_LIMIT.value,
+                        entry=f"networks[{limit_entry}]",
+                    )
                 await self._fastapi_client.append_evidence(
-                    work_record_id,
-                    source=EGRESS_REFUSED_SOURCE,
-                    payload={"event": "egress.refused", "host": host, "port": port},
+                    work_record_id, source=EGRESS_REFUSED_SOURCE, payload=payload
                 )
 
+            # No Profile allow-list leaves the proxy only the Runner Limit to refuse with:
+            # `allow_list` stays empty, so a runtime that opens the network on a Profile
+            # list (Codex) keeps it shut exactly as before.
             proxy = await stack.enter_async_context(
                 EgressProxy(
-                    allow_list,
+                    allow_list if state.egress_allow_list else None,
                     token=env[CALLBACK_TOKEN_ENV],
+                    deny_list=denied_networks,
                     resolver=self._egress_resolver,
                     on_refused=refused,
                 )
@@ -2988,6 +3029,54 @@ class RunnerRalphActivities:
             )
         return (tuple(entries) if state.mcp_servers else None), allow_list
 
+    async def _refuse_denied_destinations(
+        self,
+        work_record_id: str,
+        state: _RuntimeContextState,
+        entries: Sequence[McpServerEntry],
+        env: Mapping[str, str],
+    ) -> None:
+        """Fail the Directive at its start when something it needs is denied (§54).
+
+        The git remote, each granted MCP server's URL and each LLM endpoint: denied, the
+        Directive could only fail half-way, so it fails now, non-retryably, naming the
+        entry by its position and the destination it needed.
+        """
+
+        if not self._runner_limit.networks:
+            return
+        needed = [
+            ("git remote", _github_remote_url(state.repository)),
+            *((f"MCP server {entry.slug}", entry.url) for entry in entries if entry.url),
+            *(("LLM endpoint", value) for name, value in env.items() if name.endswith("_BASE_URL")),
+        ]
+        for needed_for, url in needed:
+            destination = url_destination(url)
+            if destination is None:
+                continue
+            index = destination_denied(self._runner_limit.networks, *destination)
+            if index is None:
+                continue
+            await _raise_recorded(
+                ApplicationError(
+                    f"this Runner's Runner Limit networks[{index}] denies {destination[0]}, "
+                    f"which this Directive's {needed_for} needs",
+                    non_retryable=True,
+                ),
+                self._fastapi_client,
+                work_record_id,
+                source=RUNNER_LIMIT_EVIDENCE_SOURCE,
+                actor=self._actor(),
+                payload={
+                    "event": "runner_limit.destination_denied",
+                    "deciding_link": GrantLink.RUNNER_LIMIT.value,
+                    "entry": f"networks[{index}]",
+                    "host": destination[0],
+                    "port": destination[1],
+                    "needed_for": needed_for,
+                },
+            )
+
     async def _resolve_credentials(
         self,
         work_record_id: str,
@@ -3832,6 +3921,7 @@ class RunnerRalphActivities:
             verb=verb,
             identifier=identifier,
             resource_type=resource_type,
+            runner_limit=self._runner_limit.tools_grant,
         )
         evidence = decision.evidence()
         refusal = (

{agentic_runner-3.21.0 → agentic_runner-3.22.0}/src/agentic_runner/config.py

@@ -11,17 +11,26 @@ operator-typed command — the Directive is dispatched, not scripted — and its
 namespace and task queues are delivered at bootstrap and never typed. ``WorkerSettings``
 remains the pod's env-only surface for the Temporal/FastAPI wiring; this is the surface a
 workstation Runner (PRD issue 47) and the Helm chart (issue 46) actually fill.
+
+``limits`` is the Runner Limit (ADR-0022 §57): a ``[limits]`` table in the file, or JSON in
+``AGENTIC_RUNNER_LIMITS`` (what the chart's ``limits`` value renders to). One that is present
+but does not parse raises here, and the Runner refuses to start: never an empty limit in
+its place, which would let the host believe a limit holds that does not.
 """
 
 from __future__ import annotations
 
+import json
 import os
 import tomllib
 from collections.abc import Mapping
 from pathlib import Path
 from typing import Any, Final
 
-from pydantic import BaseModel, ConfigDict
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from agentic_runner.runner_limit import expand_home
+from agentic_runner_contracts.runner_limit import RunnerLimit
 
 __all__ = ["CONFIG_FILE_ENV", "DEFAULT_CONFIG_FILE", "ENV_PREFIX", "RunnerConfig", "load"]
 
@@ -57,6 +66,21 @@ class RunnerConfig(BaseModel):
     openai_base_url: str | None = None
     anthropic_base_url: str | None = None
     log_level: str = "info"
+    # What this Runner's host denies every Agent on it (ADR-0022 §52); empty narrows nothing.
+    limits: RunnerLimit = Field(default_factory=RunnerLimit)
+
+    @field_validator("limits", mode="before")
+    @classmethod
+    def _expand_folder_homes(cls, value: object) -> object:
+        # A folder entry must be absolute (the contracts model), and `~/clients` is what a
+        # person writes: expanded here, against the Runner's own home, before that check.
+        if isinstance(value, Mapping) and isinstance(value.get("folders"), list | tuple):
+            folders = [
+                expand_home(folder) if isinstance(folder, str) else folder
+                for folder in value["folders"]
+            ]
+            return {**value, "folders": folders}
+        return value
 
 
 def load(
@@ -103,8 +127,14 @@ def _from_file(path: Path) -> dict[str, Any]:
 
 
 def _from_env(env: Mapping[str, str]) -> dict[str, Any]:
-    return {
+    values: dict[str, Any] = {
         field: env[f"{ENV_PREFIX}{field.upper()}"]
         for field in RunnerConfig.model_fields
         if env.get(f"{ENV_PREFIX}{field.upper()}", "").strip()
     }
+    if "limits" in values:
+        try:
+            values["limits"] = json.loads(values["limits"])
+        except ValueError as error:
+            raise ValueError(f"{ENV_PREFIX}LIMITS is not JSON: {error}") from None
+    return values

{agentic_runner-3.21.0 → agentic_runner-3.22.0}/src/agentic_runner/egress.py

@@ -13,6 +13,11 @@ What this is *not* is a kernel boundary. A process that ignores the proxy variab
 opens a raw socket is stopped only by what the host adds underneath (a pod
 NetworkPolicy); a workstation adds nothing, which is why it reports its posture as
 ``unenforced`` in the heartbeat rather than claiming the list binds.
+
+The Runner Limit's ``networks`` part (ADR-0022 §54) is a deny-list in the same syntax, read
+by the same proxy after the allow-list: a destination passes only if the Profile allows it
+and no entry denies it. Both lists are compared through :func:`parse_destination`, so a
+case, a trailing dot, a port or an IP literal's spelling means the same in either.
 """
 
 from __future__ import annotations
@@ -21,7 +26,10 @@ import asyncio
 import base64
 import contextlib
 import hmac
-from collections.abc import Awaitable, Callable, Iterable
+import ipaddress
+import re
+import socket
+from collections.abc import Awaitable, Callable, Iterable, Sequence
 from fnmatch import fnmatchcase
 from types import TracebackType
 from typing import Final
@@ -35,7 +43,10 @@ __all__ = [
     "EgressProxy",
     "Resolver",
     "destination_allowed",
+    "destination_denied",
     "host_of",
+    "parse_destination",
+    "url_destination",
 ]
 
 EGRESS_REFUSED_SOURCE: Final[str] = "runner.egress_refused"
@@ -60,6 +71,7 @@ EGRESS_ENV_NAMES: Final[frozenset[str]] = frozenset(
 _LOOPBACK: Final[str] = "127.0.0.1,localhost,::1"
 _PROXY_USER: Final[str] = "agentic"
 _PIPE_CHUNK: Final[int] = 65536
+_INET_ATON_CHARS: Final[re.Pattern[str]] = re.compile(r"[0-9a-fx.]+")
 
 Resolver = Callable[[str, int], Awaitable[tuple[str, int]]]
 
@@ -70,17 +82,91 @@ async def _system_resolver(host: str, port: int) -> tuple[str, int]:
     return str(address[0]), int(address[1])
 
 
+def normalise_host(host: str) -> str:
+    """A host as both lists compare it: lower case, no brackets, no trailing dot, and an IP
+    literal in its one canonical spelling (an IPv4-mapped IPv6 address as the IPv4 one)."""
+
+    host = host.strip().lower().strip("[]").rstrip(".")
+    try:
+        address = ipaddress.ip_address(host)
+    except ValueError:
+        return _inet_aton_spelling(host) or host
+    if isinstance(address, ipaddress.IPv6Address) and address.ipv4_mapped is not None:
+        return str(address.ipv4_mapped)
+    return address.compressed
+
+
+def _inet_aton_spelling(host: str) -> str | None:
+    """The dotted quad for an IPv4 address in a spelling ``ipaddress`` refuses and
+    ``getaddrinfo`` still connects to (``167772165``, ``0xa.0.0.5``, ``10.5``, ``012.0.0.5``):
+    left as a name, it would walk past a deny entry for the address it reaches."""
+
+    # Only the digits, hex and dots inet_aton parses: glibc's also accepts trailing garbage.
+    if not _INET_ATON_CHARS.fullmatch(host):
+        return None
+    try:
+        return socket.inet_ntoa(socket.inet_aton(host))
+    except OSError:
+        return None
+
+
+def parse_destination(entry: str) -> tuple[str, int | None]:
+    """A ``network_policy`` destination as ``(host pattern, port)``; None admits any port.
+
+    ``host``, ``host:port``, ``*.domain``, ``[v6]:port`` or a bare IPv6 literal. Raises
+    ``ValueError`` for an entry whose port is not one.
+    """
+
+    text = entry.strip()
+    if text.startswith("["):
+        host, closed, rest = text[1:].partition("]")
+        if not closed or (rest and not rest.startswith(":")):
+            raise ValueError(f"{entry!r} is not a destination")
+        raw_port: str | None = rest[1:] if rest else None
+    elif text.count(":") == 1:
+        host, _, raw_port = text.partition(":")
+    else:
+        # A bare host, or an IPv6 literal written without brackets and so without a port.
+        host, raw_port = text, None
+    if not host.strip():
+        raise ValueError(f"{entry!r} names no host")
+    if raw_port is None:
+        return normalise_host(host), None
+    if not raw_port.isdigit() or not 0 < int(raw_port) < 65536:
+        raise ValueError(f"{entry!r} has a port that is not a number from 1 to 65535")
+    return normalise_host(host), int(raw_port)
+
+
+def _matches(entry: str, host: str, port: int) -> bool:
+    try:
+        pattern, entry_port = parse_destination(entry)
+    except ValueError:
+        # Never a match, as before parsing: an allow-list entry that is not a destination
+        # admits nothing, and the Runner Limit refuses to start on one (`runner_limit`).
+        return False
+    if entry_port is not None and entry_port != port:
+        return False
+    return fnmatchcase(host, pattern)
+
+
 def destination_allowed(allow_list: Iterable[str], host: str, port: int) -> bool:
     """``host``, ``host:port`` or a ``*.domain`` pattern; a bare host admits any port."""
 
-    host = host.lower().strip("[]")
-    for entry in allow_list:
-        pattern, _, entry_port = entry.lower().partition(":")
-        if entry_port and entry_port != str(port):
-            continue
-        if fnmatchcase(host, pattern):
-            return True
-    return False
+    host = normalise_host(host)
+    return any(_matches(entry, host, port) for entry in allow_list)
+
+
+def destination_denied(deny_list: Sequence[str], host: str, port: int) -> int | None:
+    """The position of the first Runner Limit ``networks`` entry denying this, or None.
+
+    A hostname entry denies that name only: the proxy compares what the Directive asked
+    for, never what it resolves to (ADR-0022 §54).
+    """
+
+    host = normalise_host(host)
+    return next(
+        (index for index, entry in enumerate(deny_list) if _matches(entry, host, port)), None
+    )
 
 
 def host_of(url: str) -> str | None:
@@ -92,19 +178,35 @@ def host_of(url: str) -> str | None:
     return parts.hostname if parts.port is None else f"{parts.hostname}:{parts.port}"
 
 
+def url_destination(url: str) -> tuple[str, int] | None:
+    """Where a URL connects: its host and its port, the scheme's default when it names none."""
+
+    parts = urlsplit(url)
+    if not parts.hostname:
+        return None
+    try:
+        port = parts.port
+    except ValueError:
+        return None
+    return parts.hostname, port or (80 if parts.scheme in {"http", "ws"} else 443)
+
+
 class EgressProxy:
     """One attempt's forward proxy: CONNECT for TLS, absolute-form for plain HTTP."""
 
     def __init__(
         self,
-        allow_list: Iterable[str],
+        allow_list: Iterable[str] | None,
         *,
         token: str,
+        deny_list: Sequence[str] = (),
         resolver: Resolver | None = None,
-        on_refused: Callable[[str, int], Awaitable[None]] | None = None,
+        on_refused: Callable[[str, int, int | None], Awaitable[None]] | None = None,
         host: str = "127.0.0.1",
     ) -> None:
-        self.allow_list = tuple(dict.fromkeys(allow_list))
+        # None: no Profile allow-list, so only the Runner Limit's `networks` can refuse.
+        self.allow_list = None if allow_list is None else tuple(dict.fromkeys(allow_list))
+        self.deny_list = tuple(deny_list)
         self._token = token
         self._resolver = resolver or _system_resolver
         self._on_refused = on_refused
@@ -148,9 +250,13 @@ class EgressProxy:
                 await self._reply(writer, 400)
                 return
             host, port = destination
-            if not destination_allowed(self.allow_list, host, port):
+            # The Profile's list first, as the Grant is named before the Runner Limit: a
+            # destination both refuse is refused for the reason no other Runner would lift.
+            allowed = self.allow_list is None or destination_allowed(self.allow_list, host, port)
+            denied_by = None if not allowed else destination_denied(self.deny_list, host, port)
+            if not allowed or denied_by is not None:
                 if self._on_refused is not None:
-                    await self._on_refused(host, port)
+                    await self._on_refused(host, port, denied_by)
                 await self._reply(writer, 403)
                 return
             try:

{agentic_runner-3.21.0 → agentic_runner-3.22.0}/src/agentic_runner/mcp.py

@@ -31,6 +31,7 @@ from agentic_runner.tiny_http import bearer_matches, read_request, response_head
 from agentic_runner.workers.mcp_config import McpServerEntry
 from agentic_runner_contracts.grants import (
     Decision,
+    Grant,
     GrantSnapshot,
     McpServerDecision,
     decide_mcp_server,
@@ -94,19 +95,24 @@ def plan_mcp(
     *,
     consented: Collection[str] = (),
     declined: Collection[str] = (),
+    runner_limit: Grant | None = None,
 ) -> McpPlan:
     """Decide every bound server against the Effective Grant.
 
     ``consented`` / ``declined`` are the ``mcp:<server>`` names the owner has already
     answered for this step; anything else that evaluates ``confirm`` is left in
     ``to_confirm`` for the caller to ask about before a single server is started.
+    ``runner_limit`` is the Runner Limit's tools part: a server it denies is withheld,
+    never started (ADR-0022 §53).
     """
 
     granted: list[tuple[McpServerSpec, McpServerDecision]] = []
     withheld: list[tuple[McpServerSpec, McpServerDecision, str]] = []
     to_confirm: list[tuple[McpServerSpec, McpServerDecision]] = []
     for spec in servers:
-        decision = decide_mcp_server(snapshot, server=spec.slug, tools=spec.tools)
+        decision = decide_mcp_server(
+            snapshot, server=spec.slug, tools=spec.tools, runner_limit=runner_limit
+        )
         confirm = decision.decision is Decision.CONFIRM
         if decision.decision is Decision.ALLOW or (confirm and decision.verb in consented):
             granted.append((spec, decision))

{agentic_runner-3.21.0 → agentic_runner-3.22.0}/src/agentic_runner/registration.py

@@ -46,6 +46,7 @@ from agentic_runner_contracts.runner_registration import (
     HeartbeatEnvelope,
     IsolationMode,
     RecipientKey,
+    RunnerLimitReport,
 )
 from agentic_runner_contracts.runner_signature import (
     RUNNER_ID_HEADER,
@@ -258,6 +259,7 @@ class RunnerRegistrationClient:
         recipient_key: RecipientKey,
         max_concurrent_directives: int = 1,
         can_separate_uids: bool,
+        runner_limit: RunnerLimitReport | None = None,
     ) -> tuple[RunnerState, BootstrapResponse]:
         """Exchange the Runner Registration Token for this process's durable identity."""
 
@@ -271,6 +273,7 @@ class RunnerRegistrationClient:
             recipient_key=recipient_key,
             max_concurrent_directives=max_concurrent_directives,
             build_id=build_id(),
+            runner_limit=runner_limit,
         )
         payload = await self._post(BOOTSTRAP_PATH, content=request.model_dump_json(), headers={})
         response = BootstrapResponse.model_validate(payload)