agentic-runner 3.25.0__tar.gz → 3.26.0__tar.gz

{agentic_runner-3.25.0 → agentic_runner-3.26.0}/PKG-INFO

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

{agentic_runner-3.25.0 → agentic_runner-3.26.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.25.0",
+  "agentic-runner-contracts==3.26.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.25.0 → agentic_runner-3.26.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.25.0"
+__version__ = "3.26.0"
 
 __all__ = ["__version__"]

{agentic_runner-3.25.0 → agentic_runner-3.26.0}/src/agentic_runner/activities.py

@@ -36,6 +36,7 @@ from pathlib import Path
 from typing import Any, NoReturn, Protocol
 from uuid import UUID
 
+from pydantic import ValidationError
 from temporalio import activity
 from temporalio.exceptions import ApplicationError
 
@@ -46,6 +47,8 @@ from agentic_runner.attempts import (
     refuse_if_prior_attempt_alive,
 )
 from agentic_runner.auth_mode import (
+    LLM_KEY_RELEASE_REFUSED_RULE,
+    LLM_KEY_UNOPENABLE_RULE,
     AuthModeRefusedError,
     choose_auth_mode,
     is_shared_runner,
@@ -115,7 +118,7 @@ from agentic_runner.integrations.git.workspace import (
     contract_workspace_path,
 )
 from agentic_runner.integrations.github.auth import GitHubAppAuthenticationError
-from agentic_runner.llm_proxy import LlmProxy
+from agentic_runner.llm_proxy import CredentialSlot, LlmProxy
 from agentic_runner.mcp import (
     MCP_ASSEMBLY_SOURCE,
     McpPlan,
@@ -126,6 +129,7 @@ from agentic_runner.mcp import (
     plan_mcp,
 )
 from agentic_runner.message_store import MessageStore, WorkflowSignaller
+from agentic_runner.pool_key import LlmKeyOpener, LlmKeyUnopenableError
 from agentic_runner.registration import RunnerRegistrationError
 from agentic_runner.runner_limit import (
     EMPTY_RUNNER_LIMIT,
@@ -159,6 +163,7 @@ from agentic_runner.workers.contract_isolation import (
 from agentic_runner.workers.fastapi_client import (
     DirectiveTokenSource,
     WorkerFastApiClientError,
+    WorkerFastApiClientRejectionError,
     directive_token,
 )
 from agentic_runner.workers.harness_logins import (
@@ -283,6 +288,7 @@ from agentic_runner_contracts.grants import (
 )
 from agentic_runner_contracts.grants.seam import VerbDecision, decide_verb
 from agentic_runner_contracts.llm_access import LlmAccess, LlmAccessKind, provider_for
+from agentic_runner_contracts.llm_key import LlmKeyRelease, LlmKeyReleaseRequest
 from agentic_runner_contracts.questions import WORK_ASK_VERB
 from agentic_runner_contracts.redaction import redact_secret_like_text
 from agentic_runner_contracts.routing import (
@@ -292,7 +298,11 @@ from agentic_runner_contracts.routing import (
     assert_routed,
     selector_satisfied,
 )
-from agentic_runner_contracts.runner_registration import SubscriptionState
+from agentic_runner_contracts.runner_registration import (
+    ContractLlmTerms,
+    SubscriptionRight,
+    SubscriptionState,
+)
 from agentic_runner_contracts.runtime_context import (
     EGRESS_ALLOW_LIST_KEY,
     McpServerSpec,
@@ -552,6 +562,11 @@ class RunnerRalphFastApiClient(Protocol):
     ) -> dict[str, Any]:
         """Read one Directive's metered token aggregate (PRD issue 13)."""
 
+    async def release_llm_key(
+        self, work_record_id: str, llm_key_id: str, payload: Mapping[str, Any]
+    ) -> dict[str, Any]:
+        """The sealed shares of the pool's LLM Key a Directive was routed to (rev 3)."""
+
     async def report_harness_usage(self, payload: Mapping[str, Any]) -> list[dict[str, Any]]:
         """One Usage Record per model off a harness's own JSON (PRD issue 31, 17 A9)."""
 
@@ -1720,8 +1735,13 @@ class RunnerRalphActivities:
         directives_in_flight: DirectivesInFlight | None = None,
         usage_windows: UsageWindows | None = None,
         runner_limit: AppliedRunnerLimit | None = None,
+        llm_contracts: Callable[[], Sequence[ContractLlmTerms] | None] | None = None,
+        llm_keys: LlmKeyOpener | None = None,
     ) -> None:
         self._fastapi_client = fastapi_client
+        # Opens the pool's LLM Keys with the Pool Key (Spec: Runners rev 3). None, or one
+        # holding no Pool Key, fails every `llm_key` Directive closed.
+        self._llm_keys = llm_keys
         # 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
@@ -1794,6 +1814,9 @@ class RunnerRalphActivities:
         # The retry fence (runner-repo 05). None fences nothing: a process that never
         # registered has no state directory to keep the records in.
         self._attempt_records = attempt_records
+        # The Contracts the last heartbeat ack named, read at each Directive (QTS-1751).
+        # None, or a callable answering None, before any ack from a 3.25 control plane.
+        self._llm_contracts = llm_contracts
 
     def activity_callables(self) -> list[Callable[..., Any]]:
         """Return decorated activity callables for Temporal worker registration."""
@@ -2659,12 +2682,18 @@ class RunnerRalphActivities:
 
         access = routing.llm_access if routing is not None else None
         auth_mode = await self._directive_auth_mode(work_record_id, state, access)
+        attempt_directive_id = directive_id(
+            work_record_id=work_record_id, directive_number=directive_number
+        )
+        llm_key = (
+            await self._release_llm_key(work_record_id, state, access, attempt_directive_id)
+            if access is not None and access.kind == LlmAccessKind.LLM_KEY
+            else None
+        )
         await self._report_login_residue(work_record_id, state)
         facts = AttemptFacts(
             work_record_id=work_record_id,
-            directive_id=directive_id(
-                work_record_id=work_record_id, directive_number=directive_number
-            ),
+            directive_id=attempt_directive_id,
             contract_id=contract_path_segment(state.contract_id),
             agent_id=state.agent_id or "",
             persona=state.persona_slug or "",
@@ -2723,7 +2752,8 @@ class RunnerRalphActivities:
                 # API-key mode only (issue 43): a subscription Directive never has a slot
                 # to resolve, and issue 31 meters it from the harness's own output. One
                 # bearer serves the callback socket and the proxy alike. The attempt spends
-                # its own provider's slot, and a `host_key` Directive the store's alone.
+                # its own provider's slot, a `host_key` Directive the store's alone, and an
+                # `llm_key` Directive the key released for it, which leaves with the attempt.
                 proxy_attempt = await stack.enter_async_context(
                     self._llm_proxy.attempt(
                         directive_id=facts.directive_id,
@@ -2737,6 +2767,7 @@ class RunnerRalphActivities:
                             access is not None and access.kind == LlmAccessKind.HOST_KEY
                         ),
                         delivered_only=access is None and not self._personal_runner(),
+                        llm_key=llm_key,
                     )
                 )
                 callback_env.update(proxy_attempt.env(state.cli_kind))
@@ -3148,7 +3179,9 @@ class RunnerRalphActivities:
                     host_party=host_party,
                     host_key_held=self._host_key_held(state),
                     subscription=self._subscription_state(state),
+                    subscription_right=self._subscription_right(state),
                     runtime_modes=getattr(runtime, "auth_modes", frozenset({AuthMode.API_KEY})),
+                    pool_key_held=self._llm_keys is not None and self._llm_keys.holds_pool_key,
                 )
             return choose_auth_mode(
                 host_party=host_party,
@@ -3162,25 +3195,87 @@ class RunnerRalphActivities:
                 ),
             )
         except AuthModeRefusedError as refusal:
-            await _raise_recorded(
-                ApplicationError(str(refusal), type=refusal.rule, non_retryable=True),
-                self._fastapi_client,
+            await self._refuse_access(work_record_id, state, access, refusal)
+
+    async def _release_llm_key(
+        self,
+        work_record_id: str,
+        state: _RuntimeContextState,
+        access: LlmAccess,
+        attempt_directive_id: str,
+    ) -> CredentialSlot:
+        """The pool's LLM Key this Directive was routed to, opened in memory (rev 3).
+
+        The control plane releases it only to a live Runner of the key's pool for a
+        Directive in flight on it, which the Directive token proves. A refusal or a release
+        that does not open fails the Directive closed, like any access the Runner no longer
+        holds: a retry would be refused the same way.
+        """
+
+        fingerprint = self._llm_keys.fingerprint if self._llm_keys is not None else None
+        try:
+            # Refused already by `require_named_access`; this narrows the types.
+            if self._llm_keys is None or fingerprint is None:
+                raise LlmKeyUnopenableError("this Runner holds no Pool Key")
+            payload = await self._fastapi_client.release_llm_key(
                 work_record_id,
-                source=AGENT_RUNTIME_EVIDENCE_SOURCE,
-                actor=self._actor(),
-                payload={
-                    "event": (
-                        "directive.auth_mode_refused"
-                        if access is None
-                        else "directive.llm_access_refused"
-                    ),
-                    "rule": refusal.rule,
-                    "cli_kind": state.cli_kind,
-                    "host_party": host_party,
-                    "contract_id": state.contract_id,
-                    **({} if access is None else {"llm_access": access.kind}),
-                },
+                access.llm_key_id,
+                LlmKeyReleaseRequest(
+                    directive_id=attempt_directive_id, pool_key_fingerprint=fingerprint
+                ).model_dump(mode="json"),
             )
+            try:
+                release = LlmKeyRelease.model_validate(payload)
+            except ValidationError as error:
+                unreadable = "the control plane released an LLM Key this Runner cannot read"
+                raise LlmKeyUnopenableError(unreadable) from error
+            if release.llm_key_id != access.llm_key_id or release.provider != provider_for(
+                state.cli_kind
+            ):
+                raise LlmKeyUnopenableError(
+                    f"the control plane released LLM Key {release.llm_key_id} for "
+                    f"{release.provider.value}, "
+                    f"not {access.llm_key_id} for the Directive's {state.cli_kind}"
+                )
+            return self._llm_keys.open(release)
+        except WorkerFastApiClientRejectionError as error:
+            refusal = AuthModeRefusedError(
+                LLM_KEY_RELEASE_REFUSED_RULE,
+                f"the control plane refused to release LLM Key {access.llm_key_id} to this Runner "
+                f"({error.status_code})",
+            )
+        except LlmKeyUnopenableError as error:
+            refusal = AuthModeRefusedError(LLM_KEY_UNOPENABLE_RULE, str(error))
+        await self._refuse_access(work_record_id, state, access, refusal)
+
+    async def _refuse_access(
+        self,
+        work_record_id: str,
+        state: _RuntimeContextState,
+        access: LlmAccess | None,
+        refusal: AuthModeRefusedError,
+    ) -> NoReturn:
+        await _raise_recorded(
+            ApplicationError(str(refusal), type=refusal.rule, non_retryable=True),
+            self._fastapi_client,
+            work_record_id,
+            source=AGENT_RUNTIME_EVIDENCE_SOURCE,
+            actor=self._actor(),
+            payload={
+                "event": (
+                    "directive.auth_mode_refused"
+                    if access is None
+                    else "directive.llm_access_refused"
+                ),
+                "rule": refusal.rule,
+                "cli_kind": state.cli_kind,
+                "host_party": (
+                    self._routing_identity.host_party if self._routing_identity else None
+                ),
+                "contract_id": state.contract_id,
+                **({} if access is None else {"llm_access": access.kind}),
+            },
+        )
 
     def _runs_under_contract_uid(self, state: _RuntimeContextState) -> bool:
         """Whether this Directive spawns as its own Contract's uid. A Work Record with no
@@ -3219,6 +3314,19 @@ class RunnerRalphActivities:
             and self._llm_proxy.slots.holds_host(provider.value)
         )
 
+    def _subscription_right(self, state: _RuntimeContextState) -> SubscriptionRight | None:
+        """What the last ack said of this Contract's own subscription; ``no_right`` for a
+        Contract it did not name, since nothing then allowed one here."""
+
+        terms = self._llm_contracts() if self._llm_contracts is not None else None
+        if terms is None:
+            return None
+        contract_id = _optional_uuid(state.contract_id)
+        return next(
+            (term.subscription for term in terms if term.contract_id == contract_id),
+            SubscriptionRight.NO_RIGHT,
+        )
+
     def _subscription_state(self, state: _RuntimeContextState) -> SubscriptionState:
         if self._contract_isolation is None or not state.contract_id:
             return SubscriptionState.NONE

{agentic_runner-3.25.0 → agentic_runner-3.26.0}/src/agentic_runner/auth_mode.py

@@ -30,15 +30,19 @@ from typing import Final
 
 from agentic_runner.workers.agent_runtime import AuthMode
 from agentic_runner_contracts.llm_access import LlmAccess, LlmAccessKind
-from agentic_runner_contracts.runner_registration import SubscriptionState
+from agentic_runner_contracts.runner_registration import SubscriptionRight, SubscriptionState
 
 __all__ = [
     "NO_RUNTIME_SUBSCRIPTION_RULE",
     "HOST_KEY_NOT_HELD_RULE",
     "LLM_ACCESS_UNKNOWN_RULE",
-    "LLM_KEY_UNSUPPORTED_RULE",
+    "LLM_KEY_RELEASE_REFUSED_RULE",
+    "LLM_KEY_UNOPENABLE_RULE",
+    "POOL_KEY_NOT_HELD_RULE",
     "SETUP_TOKEN_REFUSED_RULE",
+    "SUBSCRIPTION_NOT_ACKNOWLEDGED_RULE",
     "SUBSCRIPTION_NOT_SIGNED_IN_RULE",
+    "SUBSCRIPTION_NO_RIGHT_RULE",
     "SUBSCRIPTION_OFF_PERSONAL_RUNNER_RULE",
     "SHARED_HOST_PARTIES",
     "SIGN_IN_NEEDS_CONTRACT_UID_RULE",
@@ -64,7 +68,14 @@ SETUP_TOKEN_REFUSED_RULE: Final[str] = "setup_token_refused"
 HOST_KEY_NOT_HELD_RULE: Final[str] = "host_key_not_held"
 SUBSCRIPTION_NOT_SIGNED_IN_RULE: Final[str] = "subscription_not_signed_in"
 SUBSCRIPTION_OFF_PERSONAL_RUNNER_RULE: Final[str] = "subscription_off_personal_runner"
-LLM_KEY_UNSUPPORTED_RULE: Final[str] = "llm_key_unsupported"
+SUBSCRIPTION_NO_RIGHT_RULE: Final[str] = "subscription_no_right"
+SUBSCRIPTION_NOT_ACKNOWLEDGED_RULE: Final[str] = "subscription_not_acknowledged"
+# An `llm_key` Directive on a Runner given no Pool Key; one whose release the control plane
+# refused; and
+# one whose release does not open here (an old Pool Key, or a share bound to another key).
+POOL_KEY_NOT_HELD_RULE: Final[str] = "pool_key_not_held"
+LLM_KEY_RELEASE_REFUSED_RULE: Final[str] = "llm_key_release_refused"
+LLM_KEY_UNOPENABLE_RULE: Final[str] = "llm_key_unopenable"
 LLM_ACCESS_UNKNOWN_RULE: Final[str] = "llm_access_unknown"
 # `claude setup-token` mints an OAuth bearer under this prefix; an Anthropic API key is
 # `sk-ant-api…`. The sealed wire carries no mode, so the value's own shape is what the
@@ -148,14 +159,24 @@ def require_named_access(
     host_party: str | None,
     host_key_held: bool,
     subscription: SubscriptionState,
+    subscription_right: SubscriptionRight | None,
     runtime_modes: Collection[AuthMode],
+    pool_key_held: bool,
 ) -> AuthMode:
     """The mode the named access runs in, or a refusal naming what is missing.
 
     ``host_key_held`` is the provider's key in this Runner's own store, serving in the
-    proxy; ``subscription`` the Contract's harness root for the Directive's kind. A
-    subscription runs only on its person's own Runner (rev 3: never on a pool Runner),
-    and only while it is signed in, unexpired and not at its usage limit.
+    proxy; ``subscription`` the Contract's harness root for the Directive's kind;
+    ``pool_key_held`` whether this Runner was given a Pool Key, without which none of the
+    pool's LLM Keys opens here. A subscription runs only on its person's own Runner (rev 3:
+    never on a pool Runner), and only while it is signed in, unexpired and not at its
+    usage limit.
+
+    ``subscription_right`` is what the last heartbeat ack said of the Contract's own
+    subscription (``llm_contracts``), so a misrouted Directive is refused here as well as
+    at the platform's routing (QTS-1349 controls 4 and 7, QTS-1751). ``None`` while no ack
+    has named the Contracts -- a control plane below 3.25 -- which leaves routing the only
+    check, as before.
     """
 
     if access.kind == LlmAccessKind.HOST_KEY:
@@ -173,6 +194,19 @@ def require_named_access(
                 f"this Runner is hosted by {host_party!r}; a subscription runs only on its "
                 "person's own Runner",
             )
+        if subscription_right == SubscriptionRight.NO_RIGHT:
+            raise AuthModeRefusedError(
+                SUBSCRIPTION_NO_RIGHT_RULE,
+                "this Directive was routed to the person's subscription, and the control plane "
+                "last told this Runner that the Contract does not allow one",
+            )
+        if subscription_right == SubscriptionRight.NOT_ACKNOWLEDGED:
+            raise AuthModeRefusedError(
+                SUBSCRIPTION_NOT_ACKNOWLEDGED_RULE,
+                "this Directive was routed to the person's subscription, and the control plane "
+                "last told this Runner that the person has not acknowledged the subscription "
+                "terms",
+            )
         if AuthMode.SUBSCRIPTION not in runtime_modes:
             raise AuthModeRefusedError(
                 NO_RUNTIME_SUBSCRIPTION_RULE,
@@ -186,11 +220,14 @@ def require_named_access(
             )
         return AuthMode.SUBSCRIPTION
     if access.kind == LlmAccessKind.LLM_KEY:
-        raise AuthModeRefusedError(
-            LLM_KEY_UNSUPPORTED_RULE,
-            "this Directive was routed to one of the pool's LLM Keys, which this Runner "
-            "release cannot open; update the Runner",
-        )
+        if not pool_key_held:
+            raise AuthModeRefusedError(
+                POOL_KEY_NOT_HELD_RULE,
+                "this Directive was routed to one of the pool's LLM Keys, and this Runner "
+                "holds no Pool Key; give it the one on the Runners page as "
+                "AGENTIC_RUNNER_POOL_KEY",
+            )
+        return AuthMode.API_KEY
     raise AuthModeRefusedError(
         LLM_ACCESS_UNKNOWN_RULE, f"this Runner does not know the LLM access {access.kind!r}"
     )

{agentic_runner-3.25.0 → agentic_runner-3.26.0}/src/agentic_runner/cli.py

@@ -54,6 +54,7 @@ from agentic_runner.callback import (
 )
 from agentic_runner.config import load as load_config
 from agentic_runner.host_store import open_workstation_store
+from agentic_runner.pool_key import POOL_KEY_ENV, PoolKeyError
 from agentic_runner.recipient_key_secret import ensure_recipient_key, in_cluster
 from agentic_runner.registration import RunnerRegistrationError, can_separate_uids, load_state
 from agentic_runner.sealed_box import RECIPIENT_KEY_FILENAME
@@ -184,6 +185,12 @@ def main(argv: Sequence[str] | None = None) -> int:
         help="comma-separated cli_kinds served through the pinned ACP bridge (codex_cli, "
         "claude_code); omitted keeps the previous install's, '' turns ACP off",
     )
+    install.add_argument(
+        "--pool-key",
+        action="store_true",
+        help=f"ask for the Pool Key of this Runner's pool (or set {POOL_KEY_ENV}), to open the "
+        "pool's LLM Keys",
+    )
     install.add_argument("--no-start", action="store_true", help="write the agent, do not start")
     install.add_argument("--root", default=None, type=Path, help="state root (default per OS)")
     for service_verb in ("start", "stop"):
@@ -503,6 +510,13 @@ def _install(arguments: argparse.Namespace, paths: workstation.OrgPaths) -> int:
         "Runner Registration Token (yours from /me/runners, or the Organisation Admin's for "
         "an Organisation Runner): "
     )
+    # Pasted too, never a flag value, for the token's reason. Taken out of the environment so
+    # the Runner this install starts reads it from the state directory, where it is kept.
+    pool_key = os.environ.pop(POOL_KEY_ENV, "").strip() or (
+        getpass.getpass("Pool Key (shown once on the Organisation's Runners page): ")
+        if arguments.pool_key
+        else None
+    )
     settings = workstation.WorkstationSettings(
         org=paths.org,
         control_plane_url=arguments.control_plane,
@@ -515,10 +529,19 @@ def _install(arguments: argparse.Namespace, paths: workstation.OrgPaths) -> int:
     try:
         lines = asyncio.run(
             workstation.install(
-                paths, settings, registration_token=token, start_service=not arguments.no_start
+                paths,
+                settings,
+                registration_token=token,
+                pool_key=pool_key,
+                start_service=not arguments.no_start,
             )
         )
-    except (workstation.CliMissingError, RunnerRegistrationError, RuntimeError) as error:
+    except (
+        workstation.CliMissingError,
+        RunnerRegistrationError,
+        PoolKeyError,
+        RuntimeError,
+    ) as error:
         print(f"install refused: {error}", file=sys.stderr)
         return 1
     for line in lines:

{agentic_runner-3.25.0 → agentic_runner-3.26.0}/src/agentic_runner/llm_proxy.py

@@ -580,6 +580,10 @@ class AttemptHandle:
     host_key_only: bool = False
     # A pool Runner's Directive that names no access (`SlotStore.resolve`).
     delivered_only: bool = False
+    # The pool's LLM Key released for this Directive (Spec: Runners rev 3): held here and
+    # nowhere else, so it is spent by this attempt only and dropped with it. Never in the
+    # slot store, which serves every attempt and is reported on the heartbeat.
+    llm_key: CredentialSlot | None = field(default=None, repr=False)
 
     def env(self, cli_kind: str) -> dict[str, str]:
         return attempt_env(cli_kind, base_url=self.base_url, token=self.token)
@@ -676,6 +680,7 @@ class LlmProxy:
         provider: str | None = None,
         host_key_only: bool = False,
         delivered_only: bool = False,
+        llm_key: CredentialSlot | None = None,
     ) -> AsyncIterator[AttemptHandle]:
         """Admit one Directive attempt for as long as it runs, and no longer.
 
@@ -697,6 +702,7 @@ class LlmProxy:
             provider=provider,
             host_key_only=host_key_only,
             delivered_only=delivered_only,
+            llm_key=llm_key,
         )
         self._attempts[attempt_id] = handle
         try:
@@ -738,7 +744,7 @@ class LlmProxy:
             await write_json(writer, 404, {"detail": "no such proxy route"})
             return
 
-        slot = self.slots.resolve(
+        slot = attempt.llm_key or self.slots.resolve(
             attempt.contract_id,
             attempt.provider,
             host_key_only=attempt.host_key_only,

agentic_runner-3.26.0/src/agentic_runner/pool_key.py

@@ -0,0 +1,175 @@
+"""The pool's Pool Key on this Runner, and the LLM Keys it opens (Spec: Runners rev 3).
+
+An Organisation's Admin creates the Pool Key in the console, which shows its private half
+once, and gives it to every Runner of the pool at install: one chart Secret for all
+replicas, a Docker env file, or ``agentic-runner install --pool-key`` on a workstation.
+The Runner reads it once at start and holds it in memory.
+
+It is kept apart from the Runner's credential store on purpose. Every value in that store
+can be named by a Contract's credential manifest and handed to a verb seam or an MCP
+server; the Pool Key must reach nothing but :class:`LlmKeyOpener`.
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import os
+from collections.abc import Mapping, MutableMapping
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Final
+
+from cryptography.hazmat.primitives.asymmetric.x25519 import X25519PrivateKey
+
+from agentic_runner.llm_proxy import LLM_SLOT_REFERENCES, CredentialSlot, LlmEndpoint
+from agentic_runner.private_state import private_read, private_write
+from agentic_runner.sealed_box import RecipientKeyStore, SealedCredentialError, open_sealed
+from agentic_runner_contracts.llm_access import PROVIDER_KEY_NAMES
+from agentic_runner_contracts.llm_key import LlmKeyRelease, join_llm_key
+from agentic_runner_contracts.sealed_credential import key_fingerprint
+
+__all__ = [
+    "POOL_KEY_ENV",
+    "POOL_KEY_FILENAME",
+    "LlmKeyOpener",
+    "LlmKeyUnopenableError",
+    "PoolKey",
+    "PoolKeyError",
+    "load_pool_key",
+    "parse_pool_key",
+    "save_pool_key",
+]
+
+POOL_KEY_ENV: Final[str] = "AGENTIC_RUNNER_POOL_KEY"
+# Where a workstation install keeps it, 0600 beside the Runner's identity.
+POOL_KEY_FILENAME: Final[str] = "pool-key"
+
+_KEY_BYTES: Final[int] = 32
+
+
+class PoolKeyError(ValueError):
+    """The Pool Key given at install is not one."""
+
+
+class LlmKeyUnopenableError(ValueError):
+    """A released LLM Key does not open on this Runner."""
+
+
+@dataclass(frozen=True, slots=True)
+class PoolKey:
+    private_key: str = field(repr=False)
+    public_key: str
+
+    @property
+    def fingerprint(self) -> str:
+        return key_fingerprint(self.public_key)
+
+
+def parse_pool_key(value: str) -> PoolKey:
+    """The X25519 private half the console showed, base64, as a :class:`PoolKey`."""
+
+    try:
+        raw = base64.b64decode(value.strip(), validate=True)
+    except (binascii.Error, ValueError) as error:
+        raise PoolKeyError(f"{POOL_KEY_ENV} must be the base64 Pool Key the console showed") from (
+            error
+        )
+    if len(raw) != _KEY_BYTES:
+        raise PoolKeyError(f"{POOL_KEY_ENV} must be a 32-byte Pool Key")
+    public = X25519PrivateKey.from_private_bytes(raw).public_key().public_bytes_raw()
+    return PoolKey(
+        private_key=base64.b64encode(raw).decode("ascii"),
+        public_key=base64.b64encode(public).decode("ascii"),
+    )
+
+
+def load_pool_key(
+    state_dir: Path | None, environ: MutableMapping[str, str] = os.environ
+) -> PoolKey | None:
+    """The Pool Key from the environment, else the workstation install's file; None if
+    the Runner was given none.
+
+    Taken out of the environment as it is read: a child process started without an
+    explicit environment would otherwise inherit it.
+    """
+
+    value = environ.pop(POOL_KEY_ENV, "").strip()
+    if not value and state_dir is not None:
+        stored = private_read(state_dir / POOL_KEY_FILENAME)
+        value = stored.decode("utf-8").strip() if stored is not None else ""
+    return parse_pool_key(value) if value else None
+
+
+def save_pool_key(state_dir: Path, value: str) -> PoolKey:
+    """Check and keep a workstation's Pool Key, for every later start of its Runner."""
+
+    pool_key = parse_pool_key(value)
+    private_write(state_dir / POOL_KEY_FILENAME, pool_key.private_key.encode("ascii"))
+    return pool_key
+
+
+class LlmKeyOpener:
+    """Opens a released LLM Key into one proxy slot (Spec: Runners rev 3).
+
+    The slot is handed to one Directive's proxy attempt and to nothing else, so the key
+    lives exactly as long as that attempt: never in the proxy's slot store, never on
+    disk, never in the Agent Runtime's environment.
+    """
+
+    def __init__(
+        self,
+        *,
+        pool_key: PoolKey | None,
+        recipient_keys: RecipientKeyStore,
+        endpoints: Mapping[str, LlmEndpoint] = LLM_SLOT_REFERENCES,
+    ) -> None:
+        self._pool_key = pool_key
+        self._recipient_keys = recipient_keys
+        self._endpoints = endpoints
+
+    @property
+    def fingerprint(self) -> str | None:
+        return self._pool_key.fingerprint if self._pool_key is not None else None
+
+    @property
+    def holds_pool_key(self) -> bool:
+        return self._pool_key is not None
+
+    def open(self, release: LlmKeyRelease) -> CredentialSlot:
+        """The key the two shares make, as a slot for the release's provider.
+
+        One error for every way a release fails to open, as :func:`open_sealed` does: a
+        share sealed to an older Pool Key, to another Runner or bound to another key are
+        the same answer to the holder, and telling them apart would be an oracle.
+        """
+
+        unopenable = f"LLM Key {release.llm_key_id} does not open with this Runner's keys"
+        if self._pool_key is None or release.pool_key_fingerprint != self._pool_key.fingerprint:
+            raise LlmKeyUnopenableError(unopenable)
+        try:
+            pool_share = open_sealed(
+                private_key=self._pool_key.private_key,
+                binding=release.pool_share_binding(),
+                ciphertext=release.pool_share,
+            )
+            platform_share = open_sealed(
+                private_key=self._recipient_private_key(release.recipient_key_id),
+                binding=release.platform_share_binding(),
+                ciphertext=release.platform_share,
+            )
+            value = join_llm_key(pool_share, platform_share)
+        except (SealedCredentialError, ValueError) as error:
+            raise LlmKeyUnopenableError(unopenable) from error
+        key_name = PROVIDER_KEY_NAMES[release.provider]
+        return self._endpoints[key_name].slot(
+            reference=key_name, key_id=release.llm_key_id, value=value
+        )
+
+    def _recipient_private_key(self, recipient_key_id: str) -> str:
+        # The previous key too: the control plane may have sealed its share just before a
+        # renewal.
+        for pair in (self._recipient_keys.current(), self._recipient_keys.previous()):
+            if pair is not None and pair.key_id == recipient_key_id:
+                return pair.private_key
+        raise SealedCredentialError("the platform share is sealed to another Recipient Key")