agentic-runner 3.25.1__tar.gz → 3.26.1__tar.gz

{agentic_runner-3.25.1 → agentic_runner-3.26.1}/PKG-INFO

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

{agentic_runner-3.25.1 → agentic_runner-3.26.1}/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.1",
+  "agentic-runner-contracts==3.26.1",
   # 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.1 → agentic_runner-3.26.1}/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.1"
+__version__ = "3.26.1"
 
 __all__ = ["__version__"]

{agentic_runner-3.25.1 → agentic_runner-3.26.1}/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 (
@@ -556,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)."""
 
@@ -1725,8 +1736,12 @@ class RunnerRalphActivities:
         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
@@ -2667,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 "",
@@ -2731,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,
@@ -2745,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))
@@ -3158,6 +3181,7 @@ class RunnerRalphActivities:
                     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,
@@ -3171,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

{agentic_runner-3.25.1 → agentic_runner-3.26.1}/src/agentic_runner/auth_mode.py

@@ -36,7 +36,9 @@ __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",
@@ -68,7 +70,12 @@ SUBSCRIPTION_NOT_SIGNED_IN_RULE: Final[str] = "subscription_not_signed_in"
 SUBSCRIPTION_OFF_PERSONAL_RUNNER_RULE: Final[str] = "subscription_off_personal_runner"
 SUBSCRIPTION_NO_RIGHT_RULE: Final[str] = "subscription_no_right"
 SUBSCRIPTION_NOT_ACKNOWLEDGED_RULE: Final[str] = "subscription_not_acknowledged"
-LLM_KEY_UNSUPPORTED_RULE: Final[str] = "llm_key_unsupported"
+# 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
@@ -154,13 +161,16 @@ def require_named_access(
     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
@@ -210,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.1 → agentic_runner-3.26.1}/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.1 → agentic_runner-3.26.1}/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.1/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")

{agentic_runner-3.25.1 → agentic_runner-3.26.1}/src/agentic_runner/service.py

@@ -85,6 +85,14 @@ from agentic_runner.llm_proxy import (
 from agentic_runner.mcp import ToolServerHealthLog
 from agentic_runner.message_store import MESSAGES_DIR, MessageStore, TemporalWorkflowSignaller
 from agentic_runner.oauth_connectors import OAuthConnectors
+from agentic_runner.pool_key import (
+    POOL_KEY_ENV,
+    POOL_KEY_FILENAME,
+    LlmKeyOpener,
+    PoolKey,
+    PoolKeyError,
+    load_pool_key,
+)
 from agentic_runner.private_state import (
     UnsafeStateError,
     ensure_private_dir,
@@ -160,6 +168,7 @@ from agentic_runner_contracts.runner_registration import (
     HostAttestation,
     IsolationMode,
     LifecycleKind,
+    PoolTerms,
     ProviderKeyReport,
     RecipientKey,
     ResourcePressure,
@@ -258,6 +267,7 @@ _PRIVATE_STATE_FILES = (
     LIFECYCLE_FILENAME,
     UID_MAP_FILENAME,
     LLM_CONTRACTS_FILENAME,
+    POOL_KEY_FILENAME,
 )
 
 
@@ -819,6 +829,10 @@ class ControlPlaneStream:
     # kept for `agentic-runner sign-in`.
     install: RunnerInstall | None = None
     state_dir: Path | None = None
+    # Rev 3: the fingerprint of the Pool Key this Runner was given; None when it was given
+    # none. Reported only once an ack named the pool (`_pool`), which a control plane on
+    # 3.26 or later does.
+    pool_key_fingerprint: str | None = None
     # Console-v2 issue 30: the OAuth Connectors whose code, tokens and verifier stay here.
     oauth: OAuthConnectors | None = None
     # ADR-0022 §57: the Runner Limit read at start and its posture; None while it is empty.
@@ -834,6 +848,7 @@ class ControlPlaneStream:
     # Rev 3: the Contracts the last ack said this Runner serves; None until an ack from a
     # control plane on 3.25 named them, and the LLM access report is sent only after.
     _llm_contracts: list[ContractLlmTerms] | None = None
+    _pool: PoolTerms | None = None
     _last_seen: tuple[float, datetime] | None = None
 
     def _observe_sleep(self, now: datetime) -> None:
@@ -1023,6 +1038,7 @@ class ControlPlaneStream:
             runner_limit=self.runner_limit,
             llm_access=self._llm_access_report(),
             install=self.install if self._llm_contracts is not None else None,
+            pool_key_fingerprint=self.pool_key_fingerprint if self._pool is not None else None,
         )
         ack = await self.client.heartbeat(self.state, envelope)
         if self.sources is not None:
@@ -1048,6 +1064,7 @@ class ControlPlaneStream:
         self._sync_delivered()
         self._manifests = list(ack.credential_manifests)
         self._take_llm_contracts(ack.llm_contracts)
+        self._take_pool(ack.pool)
         await self._sync_llm_slots()
         if ack.runner_token is not None:
             self.runner_token = ack.runner_token
@@ -1106,6 +1123,25 @@ class ControlPlaneStream:
         if self.state_dir is not None:
             save_llm_contracts(self.state_dir, terms)
 
+    def _take_pool(self, pool: PoolTerms | None) -> None:
+        """Keep the ack's pool. An ack without one (a personal Runner, or a control plane
+        below 3.26) leaves what is held."""
+
+        if pool is None or pool == self._pool:
+            return
+        self._pool = pool
+        current = pool.pool_key_fingerprint
+        if current is not None and current != self.pool_key_fingerprint:
+            # The operator's signal: this Runner opens none of the pool's LLM Keys until
+            # its install carries the Pool Key now on the Runners page.
+            _logger.warning(
+                "this Runner holds Pool Key %s, not the pool's current %s; it opens none of "
+                "the pool's LLM Keys until %s is updated",
+                self.pool_key_fingerprint or "none",
+                current,
+                POOL_KEY_ENV,
+            )
+
     async def _sync_host_keys(self) -> None:
         """The host store's keys, by the provider's key name, become the proxy's host slots
         (Spec: Runners rev 3), serving every Contract this Runner runs.
@@ -1367,6 +1403,13 @@ async def _run(
         print(f"refusing to start (runner_limit): {error}", flush=True)
         return 1
     state_dir = config.state_dir
+    try:
+        pool_key = load_pool_key(state_dir)
+    except PoolKeyError as error:
+        # Refused rather than started without it: the pool's LLM Keys would then fail
+        # every Directive routed to them, far from the typo that caused it.
+        print(f"refusing to start (pool_key_invalid): {error}", flush=True)
+        return 1
 
     readiness = readiness or Readiness(int(os.environ.get(READINESS_PORT_ENV, "").strip() or 0))
     await readiness.start()
@@ -1388,6 +1431,7 @@ async def _run(
             attestation=attestation,
             install=install,
             runner_limit=runner_limit,
+            pool_key=pool_key,
         )
     finally:
         await readiness.close()
@@ -1411,6 +1455,7 @@ async def _serve(
     attestation: HostAttestation | None,
     install: RunnerInstall | None = None,
     runner_limit: AppliedRunnerLimit = EMPTY_RUNNER_LIMIT,
+    pool_key: PoolKey | None = None,
 ) -> int:
     limit_report = runner_limit_report(
         runner_limit,
@@ -1480,6 +1525,7 @@ async def _serve(
             install=install,
             lifecycle=lifecycle,
             runner_limit=runner_limit,
+            pool_key=pool_key,
         )
     except _StoppedBeforeStartError:
         # No beat with a 10 s timeout on the way out (`_report_stop`): the control plane
@@ -1512,6 +1558,7 @@ async def _serve_registered(
     lifecycle: LifecycleOutbox,
     install: RunnerInstall | None = None,
     runner_limit: AppliedRunnerLimit = EMPTY_RUNNER_LIMIT,
+    pool_key: PoolKey | None = None,
 ) -> int:
     load = _LoadInterceptor()
     proxy = LlmProxy(slots=SlotStore(), ceilings=CeilingStore(), outbox=UsageOutbox())
@@ -1535,23 +1582,28 @@ async def _serve_registered(
     usage_windows = build_usage_windows(
         host_party=state.host_party, runtimes=runtimes, isolation=isolation, in_flight=in_flight
     )
+    # One store for both: it caches the key file, and a renewal through the stream must
+    # be the key the LLM Key opener reads too.
+    recipient_keys = RecipientKeyStore(state_dir)
+    llm_slots = llm_slot_references(
+        {
+            name: url
+            for name, url in (
+                ("openai", config.openai_base_url),
+                ("anthropic", config.anthropic_base_url),
+            )
+            if url
+        }
+    )
+    llm_keys = LlmKeyOpener(pool_key=pool_key, recipient_keys=recipient_keys, endpoints=llm_slots)
     stream = ControlPlaneStream(
         client=RunnerRegistrationClient(base_url=control_plane, client=http_client),
         state=state,
         isolation=mode,
         proxy=proxy,
-        sealed=SealedCredentialStream(RecipientKeyStore(state_dir)),
+        sealed=SealedCredentialStream(recipient_keys),
         credentials=credentials,
-        llm_slots=llm_slot_references(
-            {
-                name: url
-                for name, url in (
-                    ("openai", config.openai_base_url),
-                    ("anthropic", config.anthropic_base_url),
-                )
-                if url
-            }
-        ),
+        llm_slots=llm_slots,
         load=load,
         egress_posture=egress_posture,
         attestation=attestation,
@@ -1564,6 +1616,7 @@ async def _serve_registered(
         runner_limit=runner_limit_report(runner_limit, runtimes, egress_posture=egress_posture),
         install=install,
         state_dir=state_dir,
+        pool_key_fingerprint=llm_keys.fingerprint,
     )
     stream.sources = UserSourcePoller(
         stream=SignedIntakeStream(stream.client, state),
@@ -1631,6 +1684,7 @@ async def _serve_registered(
                 usage_windows=usage_windows,
                 runner_limit=runner_limit,
                 llm_contracts=lambda: stream.llm_contracts,
+                llm_keys=llm_keys,
                 # The wake signal rides the connection this process polls with: one
                 # namespace, the Organisation's own (PRD issue 52, map ticket 15 §2).
                 signaller=TemporalWorkflowSignaller(client),
@@ -1829,6 +1883,7 @@ def _activities(
     usage_windows: UsageWindows | None = None,
     runner_limit: AppliedRunnerLimit | None = None,
     llm_contracts: Callable[[], list[ContractLlmTerms] | None] | None = None,
+    llm_keys: LlmKeyOpener | None = None,
 ) -> list[Callable[..., Any]]:
     github_client = GitHubAppClient(
         app_id=os.getenv("GITHUB_APP_ID"),
@@ -1879,6 +1934,7 @@ def _activities(
         usage_windows=usage_windows,
         runner_limit=runner_limit,
         llm_contracts=llm_contracts,
+        llm_keys=llm_keys,
     )
     return [
         *ralph.activity_callables(),

{agentic_runner-3.25.1 → agentic_runner-3.26.1}/src/agentic_runner/sign_in.py

@@ -14,9 +14,10 @@ personal Runner serves one Contract, which the last heartbeat ack named
   ``codex login --device-auth`` with the code shown here. No code or token passes through
   the control plane.
 
-It refuses on a pool Runner, which uses only its pool's keys. It refuses a subscription
-when the ack says the Contract lacks the right or the person has not acknowledged, and
-says which.
+It refuses on a pool Runner, which uses only its pool's keys. It offers a subscription
+only when the ack says the Contract allows it; otherwise it says which of the right or
+the person's acknowledgment is missing, names the console page that turns it on, and
+offers the key (QTS-1776).
 """
 
 from __future__ import annotations
@@ -92,14 +93,21 @@ class SignIn:
 
     async def _one(self, cli_kind: str) -> int:
         label = _LABELS[cli_kind]
-        answer = self.ask(
-            f"{label}: sign in with your [s]ubscription, store an API [k]ey, or skip? [s/k/N] "
-        )
+        offer = self._subscription_offer()
+        if isinstance(offer, str):
+            # Offering `[s]` and then refusing it is what sent an Organisation Admin looking
+            # for a switch nothing named (QTS-1776).
+            self.say(f"{label}: {offer}")
+            answer = self.ask(f"{label}: store an API [k]ey, or skip? [k/N] ")
+        else:
+            answer = self.ask(
+                f"{label}: sign in with your [s]ubscription, store an API [k]ey, or skip? [s/k/N] "
+            )
         choice = answer.strip().lower()[:1]
         if choice == "k":
             return self._key(cli_kind)
-        if choice == "s":
-            return await self._subscription(cli_kind)
+        if choice == "s" and not isinstance(offer, str):
+            return await self._subscription(offer, cli_kind)
         self.say(f"{label}: skipped")
         return 0
 
@@ -118,39 +126,38 @@ class SignIn:
         )
         return 0
 
-    async def _subscription(self, cli_kind: str) -> int:
-        contract = self._contract()
-        if contract is None:
-            return 1
-        if contract.subscription == SubscriptionRight.NO_RIGHT:
-            self.say(
-                "refusing a subscription: your Contract does not allow your own subscription. "
-                "Ask an Organisation Admin to turn it on, or store an API key instead"
-            )
-            return 1
-        if contract.subscription == SubscriptionRight.NOT_ACKNOWLEDGED:
-            self.say(
-                "refusing a subscription: you have not acknowledged the subscription terms. "
-                "Acknowledge them on your Contract in the console, then run this again"
-            )
-            return 1
+    async def _subscription(self, contract: ContractLlmTerms, cli_kind: str) -> int:
         returncode = await self.subscription(str(contract.contract_id), cli_kind)
         if returncode != 0:
             self.say(f"{_LABELS[cli_kind]}: the sign-in exited {returncode}; nothing changed")
         return returncode
 
-    def _contract(self) -> ContractLlmTerms | None:
+    def _subscription_offer(self) -> ContractLlmTerms | str:
+        """The one Contract a subscription signs in, or why the ack offers none."""
+
         if self.contracts is None:
-            self.say(
-                "refusing a subscription: this Runner has not yet been told its Contract. "
-                "Start it, wait for its first heartbeat, and run this again (the control "
-                "plane must be on contracts 3.25 or later)"
+            return (
+                "no subscription yet: this Runner has not yet been told its Contract. Start "
+                "it, wait for its first heartbeat, and run this again (the control plane must "
+                "be on contracts 3.25 or later)"
             )
-            return None
         if len(self.contracts) != 1:
-            self.say(
-                f"refusing a subscription: a personal Runner serves one Contract, and the "
-                f"control plane named {len(self.contracts)}"
+            return (
+                "no subscription: a personal Runner serves one Contract, and the control "
+                f"plane named {len(self.contracts)}"
+            )
+        contract = self.contracts[0]
+        if contract.subscription == SubscriptionRight.NO_RIGHT:
+            # TODO(QTS-1744): name the Contract editor once the right moves onto the Contract.
+            return (
+                "your own subscription is off for this Runner. An Organisation Admin turns it "
+                "on in the console with Allow subscription sign-in, on this Runner under "
+                "Personal Runners on /orgs/<organisation>/runners"
+            )
+        if contract.subscription == SubscriptionRight.NOT_ACKNOWLEDGED:
+            return (
+                "your own subscription is on for this Runner, and you have not acknowledged "
+                "the subscription terms. Acknowledge them in the console on My Contracts "
+                "(/me/contracts), then run this again"
             )
-            return None
-        return self.contracts[0]
+        return contract

{agentic_runner-3.25.1 → agentic_runner-3.26.1}/src/agentic_runner/testing/control_plane.py

@@ -26,6 +26,9 @@ Contracts 3.25 (Spec: Runners rev 3): every ack names the one Contract this fake
 ``llm_contracts``, with ``subscription`` as its right, so a Runner reports the LLM access it
 holds for it; :attr:`FakeControlPlane.llm_access` keeps each report. ``subscription``
 ``None`` answers as a control plane below 3.25 does: no Contract terms at all.
+
+Contracts 3.26: :attr:`FakeControlPlane.pool` is the ack's pool and its current Pool Key;
+None, the default, answers for a personal Runner or a control plane below 3.26.
 """
 
 from __future__ import annotations
@@ -69,6 +72,7 @@ from agentic_runner_contracts.runner_registration import (
     FloorState,
     HeartbeatAck,
     HeartbeatEnvelope,
+    PoolTerms,
     RunnerIdentityMaterial,
     SubscriptionRight,
 )
@@ -179,6 +183,7 @@ class FakeControlPlane:
     # The ack's word on whether the person may sign this Contract in with their own
     # subscription; None leaves `llm_contracts` out, as a control plane below 3.25 does.
     subscription: SubscriptionRight | None = SubscriptionRight.NO_RIGHT
+    pool: PoolTerms | None = None
 
     bootstraps: list[BootstrapRequest] = field(default_factory=list)
     runner_ids: list[UUID] = field(default_factory=list)
@@ -459,6 +464,7 @@ class FakeControlPlane:
                     ContractLlmTerms(contract_id=self.contract_id, subscription=self.subscription)
                 ]
             ),
+            pool=self.pool,
         )
         return _Answer(200, ack.model_dump(mode="json"))
 

{agentic_runner-3.25.1 → agentic_runner-3.26.1}/src/agentic_runner/workers/fastapi_client.py

@@ -176,6 +176,20 @@ class RunnerFastApiClient:
         records = result.get("records")
         return records if isinstance(records, list) else []
 
+    async def release_llm_key(
+        self, work_record_id: str, llm_key_id: str, payload: Mapping[str, Any]
+    ) -> dict[str, Any]:
+        """The two sealed shares of the LLM Key a Directive's ``llm_access`` names (Spec:
+        Runners rev 3). ``payload`` is ``LlmKeyReleaseRequest``'s shape; the Directive
+        token says which Runner and Directive ask, which is what the control plane releases
+        against."""
+
+        return await self._post(
+            f"{self._prefix}/work-records/{_path_segment(work_record_id)}"
+            f"/llm-keys/{_path_segment(llm_key_id)}/release",
+            payload,
+        )
+
     async def append_evidence(
         self,
         work_record_id: str,

{agentic_runner-3.25.1 → agentic_runner-3.26.1}/src/agentic_runner/workstation.py

@@ -49,6 +49,7 @@ from agentic_runner.cli_floor import CLI_FLOORS, CLI_NAMES, meets_floor, parse_c
 from agentic_runner.config import CONFIG_FILE_ENV
 from agentic_runner.host_store import open_workstation_store
 from agentic_runner.lifecycle import LifecycleOutbox
+from agentic_runner.pool_key import parse_pool_key, save_pool_key
 from agentic_runner.registration import load_state
 from agentic_runner.service import HEARTBEAT_STAMP_NAME, PIDFILE_NAME
 from agentic_runner.workers.acp_runtime import ACP_BRIDGES
@@ -637,6 +638,7 @@ async def install(
     settings: WorkstationSettings,
     *,
     registration_token: str,
+    pool_key: str | None = None,
     platform: str = sys.platform,
     home: Path | None = None,
     start_service: bool = True,
@@ -650,9 +652,16 @@ async def install(
     prompt, never stored: the identity bootstrap hands back is what every later start uses,
     and a lost state directory means a reinstall and a re-delivery of any sealed value
     (22 A4), by design.
+
+    ``pool_key`` is the Organisation's Pool Key, for a Runner of its pool that opens the
+    pool's LLM Keys (Spec: Runners rev 3). Unlike the token it is kept, 0600 in the state
+    directory, because every start of the Runner needs it.
     """
 
     require_any_cli(settings.path)
+    if pool_key:
+        # Checked before anything registers; kept only once something has.
+        parse_pool_key(pool_key)
     paths.create()
     settings.save(paths)
     already_registered = load_state(paths.state_dir) is not None
@@ -664,6 +673,8 @@ async def install(
         registration_token=registration_token,
         isolation=IsolationMode.NONE,
     )
+    if pool_key:
+        save_pool_key(paths.state_dir, pool_key)
     LifecycleOutbox(paths.state_dir).add(LifecycleKind.INSTALL, datetime.now(UTC))
     definition = service_definition(paths, settings, platform=platform, home=home)
     definition.path.parent.mkdir(parents=True, exist_ok=True)