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

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

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

{agentic_runner-3.22.0 → agentic_runner-3.23.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.22.0",
+  "agentic-runner-contracts==3.23.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.22.0 → agentic_runner-3.23.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.22.0"
+__version__ = "3.23.0"
 
 __all__ = ["__version__"]

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

@@ -3661,8 +3661,9 @@ class RunnerRalphActivities:
 
         The Grant snapshot is the one thing that no longer arrives either way when this
         Runner has a heartbeat stream (PRD issue 44): the control plane pushes it on
-        change and the link holds the current one per Agent, so narrowing bites at the
-        next *verb* rather than the next Directive. ``grant_snapshot`` carried on the
+        change and the link holds the current one per Agent and Contract, read under the
+        Contract this context names for the Work Record (QTS-1706), so narrowing bites at
+        the next *verb* rather than the next Directive. ``grant_snapshot`` carried on the
         input is the link-less host's source and is ignored wherever a link is attached.
         """
 
@@ -3677,7 +3678,7 @@ class RunnerRalphActivities:
                 work_record_id=work_record_id,
             )
         snapshot_payload = (
-            self._heartbeat_link.payload_for(runtime_context.agent_id)
+            self._heartbeat_link.payload_for(runtime_context.agent_id, runtime_context.contract_id)
             if self._heartbeat_link is not None
             else dict(grant_snapshot or {})
         )
@@ -4151,7 +4152,10 @@ class RunnerRalphActivities:
 
         if self._heartbeat_link is None:
             return state.grant_snapshot
-        return self._heartbeat_link.snapshot_for(state.agent_id) or state.grant_snapshot
+        return (
+            self._heartbeat_link.snapshot_for(state.agent_id, state.contract_id)
+            or state.grant_snapshot
+        )
 
     async def _require_live_link(
         self,
@@ -4175,7 +4179,7 @@ class RunnerRalphActivities:
         if self._heartbeat_link is None:
             return
         try:
-            await self._heartbeat_link.require_ready(state.agent_id, verb=verb)
+            await self._heartbeat_link.require_ready(state.agent_id, state.contract_id, verb=verb)
         except SeamUnavailableError as error:
             await self._fastapi_client.append_evidence(
                 work_record_id,

{agentic_runner-3.22.0 → agentic_runner-3.23.0}/src/agentic_runner/heartbeat_link.py

@@ -8,9 +8,11 @@ changed.
 
 Three things live together because they are one fact about "may this verb run now":
 
-* **The per-Agent store.** Snapshots are keyed by Agent and read only by that Agent's verb
-  evaluations (17's structural rule): a Runner shared by many Contracts never mixes them,
-  and a push *replaces* an Agent's snapshot rather than merging into it.
+* **The per-Agent, per-Contract store.** Snapshots are keyed by Agent and the Contract
+  they decide for, and read only by that Agent's verb evaluations on a Work Record under
+  that Contract (17's structural rule, QTS-1706): a Runner shared by many Contracts never
+  mixes them -- not even for an Organisation Agent working under two Owners' Contracts at
+  once -- and a push *replaces* a snapshot rather than merging into it.
 * **The acknowledgement.** Each snapshot carries a version, and every heartbeat says which
   versions this Runner holds, which is how the control plane tells "applied" from "sent".
 * **The liveness clock.** Staleness is a property of the *link*, not a per-snapshot TTL
@@ -89,6 +91,10 @@ class HeartbeatStream(Protocol):
     async def exchange(self, applied: Sequence[AppliedSnapshot]) -> HeartbeatAck: ...
 
 
+# (agent_id, contract_id); the Contract is None for a push from a control plane below 3.23.
+_Key = tuple[str, str | None]
+
+
 @dataclass(frozen=True, slots=True)
 class _Held:
     version: str
@@ -120,7 +126,7 @@ class HeartbeatLink:
         # Eviction is by read rather than by push because an Agent whose Work Record
         # finished is never read again, while one under a running Directive is read at
         # every verb -- and `max_concurrent_directives` is itself bounded by this number.
-        self._held: OrderedDict[str, _Held] = OrderedDict()
+        self._held: OrderedDict[_Key, _Held] = OrderedDict()
         self._tags: dict[str, str] | None = None
         self._last_ack: float | None = None
         self._seen_monotonic, self._seen_wall = self._clock()
@@ -128,26 +134,44 @@ class HeartbeatLink:
 
     # ------------------------------------------------------------------ the store
 
-    def snapshot_for(self, agent_id: str | None) -> GrantSnapshot | None:
-        """This Agent's pushed snapshot, or ``None`` if none was ever pushed."""
+    def snapshot_for(self, agent_id: str | None, contract_id: str | None) -> GrantSnapshot | None:
+        """This Agent's pushed snapshot for this Contract, or ``None`` if none was pushed."""
 
-        held = self._touch(agent_id)
+        held = self._touch(agent_id, contract_id)
         return held.snapshot if held else None
 
-    def payload_for(self, agent_id: str | None) -> dict[str, Any]:
+    def payload_for(self, agent_id: str | None, contract_id: str | None) -> dict[str, Any]:
         """The snapshot exactly as the control plane wrote it (ADR-0013 §3)."""
 
-        held = self._touch(agent_id)
+        held = self._touch(agent_id, contract_id)
         return dict(held.payload) if held else {}
 
-    def _touch(self, agent_id: str | None) -> _Held | None:
-        if agent_id is None:
+    def _touch(self, agent_id: str | None, contract_id: str | None) -> _Held | None:
+        found = self._find(agent_id, contract_id)
+        if found is None:
             return None
-        held = self._held.get(agent_id)
-        if held is not None:
-            self._held.move_to_end(agent_id)
+        key, held = found
+        self._held.move_to_end(key)
         return held
 
+    def _find(self, agent_id: str | None, contract_id: str | None) -> tuple[_Key, _Held] | None:
+        """The snapshot deciding this Agent's verbs on a Work Record under this Contract.
+
+        Never another Contract's: a snapshot an older control plane pushed without a
+        Contract answers only for the Contract it names itself, or for none when it is the
+        held snapshot that refuses every verb.
+        """
+
+        if agent_id is None:
+            return None
+        if contract_id is not None and (agent_id, contract_id) in self._held:
+            return (agent_id, contract_id), self._held[(agent_id, contract_id)]
+        unkeyed = self._held.get((agent_id, None))
+        # The payload, not the parsed snapshot: `from_payload` reads a null as "None".
+        if unkeyed is None or unkeyed.payload.get("contract_id") not in (None, contract_id):
+            return None
+        return (agent_id, None), unkeyed
+
     @property
     def tags(self) -> dict[str, str] | None:
         """This Runner's Tags as the last ack carried them (ADR-0022 §13).
@@ -160,28 +184,45 @@ class HeartbeatLink:
 
     def applied(self) -> list[AppliedSnapshot]:
         return [
-            AppliedSnapshot(agent_id=UUID(agent_id), version=held.version)
-            for agent_id, held in sorted(self._held.items())
+            AppliedSnapshot(
+                agent_id=UUID(agent_id),
+                contract_id=None if contract_id is None else UUID(contract_id),
+                version=held.version,
+            )
+            for (agent_id, contract_id), held in sorted(
+                self._held.items(), key=lambda item: (item[0][0], item[0][1] or "")
+            )
         ]
 
     def apply(self, ack: HeartbeatAck) -> None:
-        """Apply one ack's pushes: snapshots per Agent, ceilings per Contract, the Tags.
+        """Apply one ack's pushes: snapshots per Agent and Contract, ceilings per Contract,
+        the Tags.
 
         Replacement, never a merge. A narrowed Grant that merged into what it narrowed
         would leave the wider entry standing, which is the one mistake this whole layer
-        exists to prevent.
+        exists to prevent. For the same reason a push without a Contract, from a control
+        plane below 3.23, replaces every snapshot of its Agent, and a push with one
+        replaces the Agent's snapshot that had none.
         """
 
         if ack.tags is not None:
             self._tags = dict(ack.tags)
         for push in ack.grant_pushes:
             agent_id = str(push.agent_id)
-            self._held[agent_id] = _Held(
+            key: _Key = (agent_id, None if push.contract_id is None else str(push.contract_id))
+            replaced = (
+                [entry for entry in self._held if entry[0] == agent_id]
+                if push.contract_id is None
+                else [(agent_id, None)]
+            )
+            for stale in replaced:
+                self._held.pop(stale, None)
+            self._held[key] = _Held(
                 version=push.version,
                 payload=dict(push.snapshot),
                 snapshot=GrantSnapshot.from_payload(push.snapshot),
             )
-            self._held.move_to_end(agent_id)
+            self._held.move_to_end(key)
         while len(self._held) > SNAPSHOT_PUSH_MAX:
             self._held.popitem(last=False)
         if self._ceilings is None:
@@ -210,13 +251,16 @@ class HeartbeatLink:
         self._woke = False
         return ack
 
-    async def require_ready(self, agent_id: str | None, *, verb: str) -> None:
+    async def require_ready(
+        self, agent_id: str | None, contract_id: str | None, *, verb: str
+    ) -> None:
         """Refuse a privileged verb this Runner is in no position to decide.
 
         Order matters: a wake is answered with a heartbeat *before* staleness is read, so
         a laptop that slept re-hears the control plane instead of acting on a snapshot
         from before the sleep (23 item 4); and a Runner holding no snapshot for an Agent
-        refuses rather than running it unattenuated -- absence is never permission.
+        under this Work Record's Contract refuses rather than running it unattenuated, or
+        on another Contract's chain -- absence is never permission.
         """
 
         if self._observe_wake():
@@ -236,10 +280,11 @@ class HeartbeatLink:
                 f"{'none' if age is None else f'{age:.0f}s'} old, past the "
                 f"{self._stale_after:.0f}s liveness bound",
             )
-        if agent_id is not None and agent_id not in self._held:
+        if agent_id is not None and self._find(agent_id, contract_id) is None:
             raise SeamUnavailableError(
                 SNAPSHOT_MISSING_REASON,
-                f"{verb!r} is refused: no Grant snapshot has been pushed for Agent {agent_id}",
+                f"{verb!r} is refused: no Grant snapshot has been pushed for Agent {agent_id} "
+                f"under Contract {contract_id}",
             )
 
     def _age(self) -> float | None: