agentic-runner 3.30.4__tar.gz → 3.31.1__tar.gz

{agentic_runner-3.30.4 → agentic_runner-3.31.1}/PKG-INFO

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

{agentic_runner-3.30.4 → agentic_runner-3.31.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.30.4",
+  "agentic-runner-contracts==3.31.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.30.4 → agentic_runner-3.31.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.30.4"
+__version__ = "3.31.1"
 
 __all__ = ["__version__"]

{agentic_runner-3.30.4 → agentic_runner-3.31.1}/src/agentic_runner/activities.py

@@ -73,6 +73,7 @@ from agentic_runner.callback import (
     VerbRequest,
     VerbResponse,
 )
+from agentic_runner.connections import contract_refusal
 from agentic_runner.credentials import (
     CREDENTIAL_RESOLVED_SOURCE,
     CREDENTIAL_UNRESOLVABLE_SOURCE,
@@ -1737,8 +1738,15 @@ class RunnerRalphActivities:
         runner_limit: AppliedRunnerLimit | None = None,
         llm_contracts: Callable[[], Sequence[ContractLlmTerms] | None] | None = None,
         llm_keys: LlmKeyOpener | None = None,
+        connection_organisation: Callable[[], UUID | None] | None = None,
     ) -> None:
         self._fastapi_client = fastapi_client
+        # The Organisation whose connection this Worker polls (Spec: Runners rev 14). One
+        # process holds every connected Organisation's credentials, harness roots and
+        # Workspaces, so a Directive is served only under a Contract of its own
+        # connection's Organisation (`_assert_connection_serves`). None, or a callable
+        # answering None, on a Runner polling only the namespace it registered in.
+        self._connection_organisation = connection_organisation
         # 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
@@ -1891,6 +1899,59 @@ class RunnerRalphActivities:
             return self._routing_identity
         return replace(self._routing_identity, tags=acked)
 
+    async def _assert_connection_serves(
+        self, work_record_id: str, contract_id: str | None, *, workspace_path: str = ""
+    ) -> None:
+        """Fail closed unless the Contract belongs to this Worker's connection's
+        Organisation (Spec: Runners rev 14, QTS-2252).
+
+        Called once the Contract is known and before any Workspace, credential or
+        harness root is touched: a Directive delivered in one Organisation's namespace
+        that names another's Contract -- or another Contract's Workspace -- would
+        otherwise run under credentials and a sign-in that Organisation never gave it.
+        Not retryable: the same task on the same connection is refused again.
+        """
+
+        organisation = self._connection_organisation() if self._connection_organisation else None
+        if organisation is None:
+            return
+        terms = (self._llm_contracts() if self._llm_contracts is not None else None) or ()
+        reason = contract_refusal(organisation, terms, _optional_uuid(contract_id))
+        if (
+            reason is None
+            and workspace_path
+            and not self._within_contract_workspaces(workspace_path, contract_id)
+        ):
+            reason = "workspace_of_another_contract"
+        if reason is None:
+            return
+        refusal = ApplicationError(
+            f"refused: {reason} on the connection to Organisation {organisation}",
+            type=reason,
+            non_retryable=True,
+        )
+        if not work_record_id:
+            raise refusal
+        await _raise_recorded(
+            refusal,
+            self._fastapi_client,
+            work_record_id,
+            source=_ROUTING_EVIDENCE_SOURCE,
+            actor=self._actor(),
+            payload={
+                "event": "directive.routing_refused",
+                "reason": reason,
+                "organisation_id": str(organisation),
+                "contract_id": contract_id,
+            },
+        )
+
+    def _within_contract_workspaces(self, workspace_path: str, contract_id: str | None) -> bool:
+        if self._workspace_root is None:
+            return False
+        contract_root = self._workspace_root.resolve() / contract_path_segment(contract_id)
+        return Path(workspace_path).resolve().is_relative_to(contract_root)
+
     def _actor(self) -> str:
         return (
             f"runner:{self._routing_identity.runner_id}"
@@ -3835,6 +3896,9 @@ class RunnerRalphActivities:
         runtime_context = await self._runtime_context_resolver.resolve(
             work_record_id, agent_id=agent_id or None
         )
+        await self._assert_connection_serves(
+            work_record_id, runtime_context.contract_id, workspace_path=workspace_path
+        )
         resolved_workspace = Path(workspace_path) if workspace_path else None
         if resolved_workspace is None and self._workspace_root is not None:
             resolved_workspace = _contract_workspace_path(
@@ -5990,6 +6054,7 @@ class RunnerRalphActivities:
         """
 
         await self._assert_routed(request)
+        await self._assert_connection_serves("", request.contract_id or None)
         isolation = self._contract_isolation
         segment = contract_path_segment(request.contract_id or None)
         held = (

{agentic_runner-3.30.4 → agentic_runner-3.31.1}/src/agentic_runner/cli.py

@@ -21,6 +21,11 @@ through the vendor's own sign-in in this terminal, or an API key stored in the R
 own store (``sign_in.py``, Spec: Runners rev 3). No ids, and no code or token passes
 through the control plane.
 
+``login [name]`` makes this Runner the person's with a device flow -- a code shown here,
+confirmed in the browser, no token copied -- and ``connect [organisation]`` asks for a
+connection to an Organisation they belong to (Spec: Runners rev 14). One Runner then takes
+the work of every Organisation it is connected to, under one concurrency limit.
+
 ``skill install | print`` hands the setup skill to the person's own Claude Code or Codex
 (``skill.py``, console-v2 issue 21).
 
@@ -42,6 +47,7 @@ import os
 import re
 import socket
 import sys
+import webbrowser
 from collections.abc import Sequence
 from pathlib import Path
 
@@ -108,6 +114,8 @@ _NAME_HELP = (
     "machine takes it"
 )
 _INSTALLED_NAME_HELP = "the Runner's name; omitted when this machine runs one Runner"
+# `login` on a workstation with no name: the console then lists it under this one.
+DEFAULT_LOGIN_NAME = "runner"
 
 
 def _old_org_flag(parser: argparse.ArgumentParser) -> None:
@@ -208,6 +216,34 @@ def main(argv: Sequence[str] | None = None) -> int:
     )
     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)")
+    login = subcommands.add_parser(
+        "login",
+        help="make this Runner yours: confirm a code in the browser, no token to copy",
+    )
+    login.add_argument(
+        "name",
+        nargs="?",
+        default=None,
+        help=f"{_NAME_HELP}; default `{DEFAULT_LOGIN_NAME}` on a workstation, `RUNNER_NAME` "
+        "in a container",
+    )
+    login.add_argument(
+        "--control-plane", default=os.environ.get(CONTROL_PLANE_ENV), help="control plane URL"
+    )
+    login.add_argument("--temporal-plaintext", action="store_true", help=argparse.SUPPRESS)
+    login.add_argument("--no-start", action="store_true", help="write the agent, do not start")
+    login.add_argument("--no-browser", action="store_true", help="show the link, do not open it")
+    login.add_argument("--root", default=None, type=Path, help="state root (default per OS)")
+
+    connect = subcommands.add_parser(
+        "connect", help="connect your Runner to an Organisation you belong to"
+    )
+    connect.add_argument(
+        "organisation", nargs="?", help="the Organisation's name or id; omitted lists yours"
+    )
+    connect.add_argument("--name", default=None, help=_INSTALLED_NAME_HELP)
+    connect.add_argument("--root", default=None, type=Path, help=argparse.SUPPRESS)
+
     for service_verb in ("start", "stop"):
         driven = subcommands.add_parser(
             service_verb, help=f"{service_verb} one workstation Runner's login agent"
@@ -380,6 +416,10 @@ def main(argv: Sequence[str] | None = None) -> int:
             )
             return 2
         return asyncio.run(service.run(attestation=_image_attestation(), install=_run_install()))
+    if arguments.command == "login":
+        return _login(arguments)
+    if arguments.command == "connect":
+        return _connect(arguments)
     if arguments.command in {"install", "start", "stop", "credential"}:
         return _workstation(arguments)
     if arguments.command == "restart":
@@ -597,6 +637,101 @@ def _sign_in(arguments: argparse.Namespace) -> int:
     return asyncio.run(service.sign_in(arguments.runtime, store=store, method=arguments.method))
 
 
+def _login(arguments: argparse.Namespace) -> int:
+    """``login [name]``: a workstation Runner gets its login agent, as ``install`` gives one;
+    in a container the identity goes to the state directory ``run`` reads."""
+
+    if not arguments.control_plane:
+        print(f"--control-plane (or {CONTROL_PLANE_ENV}) is required", file=sys.stderr)
+        return 2
+
+    def say(line: str) -> None:
+        print(line, flush=True)
+
+    def open_browser(url: str) -> object:
+        return None if arguments.no_browser or _in_container() else webbrowser.open(url)
+
+    try:
+        if _in_container():
+            name = arguments.name or _container_name()
+            _, outcome = asyncio.run(
+                service.login(
+                    state_dir=_state_dir(),
+                    control_plane=arguments.control_plane,
+                    name=workstation.validate_name(name) if name else None,
+                    say=say,
+                    open_browser=open_browser,
+                )
+            )
+            print(outcome)
+            return 0
+        paths = workstation.RunnerPaths(
+            root=arguments.root or workstation.default_root(),
+            name=workstation.validate_name(arguments.name or DEFAULT_LOGIN_NAME),
+        )
+        settings = workstation.WorkstationSettings(
+            control_plane_url=arguments.control_plane,
+            temporal_tls=not arguments.temporal_plaintext,
+            path=os.environ.get("PATH", ""),
+            install_channel=workstation.install_channel(),
+            acp_cli_kinds=_acp_cli_kinds(None, paths),
+        )
+        lines = asyncio.run(
+            workstation.login(
+                paths,
+                settings,
+                say=say,
+                open_browser=open_browser,
+                start_service=not arguments.no_start,
+            )
+        )
+    except (
+        workstation.CliMissingError,
+        RunnerRegistrationError,
+        RuntimeError,
+        ValueError,
+    ) as error:
+        print(f"login refused: {error}", file=sys.stderr)
+        return 1
+    for line in lines:
+        print(line)
+    return 0
+
+
+def _connect(arguments: argparse.Namespace) -> int:
+    if arguments.name or not _in_container():
+        try:
+            paths = _runner_paths(arguments, how="name one with --name")
+        except ValueError as error:
+            print(error, file=sys.stderr)
+            return 2
+        state_dir = paths.state_dir
+        control_plane = workstation.WorkstationSettings.load(paths).control_plane_url
+    else:
+        state_dir = _state_dir()
+        control_plane = os.environ.get(CONTROL_PLANE_ENV, "").strip()
+    try:
+        return asyncio.run(
+            service.connect(
+                state_dir=state_dir,
+                control_plane=control_plane,
+                organisation=arguments.organisation,
+                ask=input,
+                say=lambda line: print(line, file=sys.stderr),
+            )
+        )
+    except RunnerRegistrationError as error:
+        print(f"connect refused ({error.reason}): {error}", file=sys.stderr)
+        return 1
+
+
+def _container_name() -> str | None:
+    """The name a container Runner reports: ``RUNNER_NAME``, else none for the control plane
+    to choose, since a container id is no name a person picked."""
+
+    return os.environ.get("RUNNER_NAME", "").strip() or None
+
+
 def _install(arguments: argparse.Namespace, paths: workstation.RunnerPaths) -> int:
     if not arguments.control_plane:
         print(f"--control-plane (or {CONTROL_PLANE_ENV}) is required", file=sys.stderr)

agentic_runner-3.31.1/src/agentic_runner/connections.py

@@ -0,0 +1,315 @@
+"""One machine, many connections (Spec: Runners rev 14).
+
+A person's Runner takes work from every Organisation they connected it to: one Temporal
+Worker per connection, each polling ``runner.{runner_id}`` in its own namespace with its own
+Runner Token, all reconciled from the heartbeat ack. The machine has one concurrency limit,
+from its own config, shared by all of them: the first work in takes a free slot.
+
+**The shared limit.** Each Worker gets a :class:`ConnectionSlots`, a custom slot supplier
+over one :class:`MachineSlots`. Temporal reserves a slot *before* it polls, and an idle
+poll holds its reservation for up to a minute; counting reservations against the machine
+would let one idle connection's poll starve every other. So a reservation is granted while
+the slots in use on the machine, plus this connection's own unused reservations, are below
+the limit. One connection alone therefore never exceeds the limit, exactly as
+``max_concurrent_activities`` did; across connections, polls already outstanding can each
+bring an activity in the same instant, so N connections can briefly run limit + N - 1. The
+spec puts the machine-wide limit in routing ("Routing counts the Runner's load across all
+its connections ... so least-loaded and the limit see the whole machine"): the control
+plane does not send a Directive to a full machine. This is the backstop.
+
+**Pause.** A paused connection makes no new reservation, so its Worker stops polling once
+the polls already outstanding return, while what it already runs finishes. The control
+plane routes nothing to a paused connection, so those polls come back empty.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+import threading
+from collections.abc import Awaitable, Callable, Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+from uuid import UUID
+
+from temporalio.worker import (
+    CustomSlotSupplier,
+    FixedSizeSlotSupplier,
+    SlotMarkUsedContext,
+    SlotPermit,
+    SlotReleaseContext,
+    SlotReserveContext,
+    WorkerTuner,
+)
+
+from agentic_runner_contracts.runner_registration import ContractLlmTerms, RunnerConnection
+
+__all__ = [
+    "ConnectionSlots",
+    "ConnectionWorkers",
+    "MachineSlots",
+    "contract_refusal",
+]
+
+_logger = logging.getLogger(__name__)
+
+
+def contract_refusal(
+    organisation: UUID, terms: Sequence[ContractLlmTerms], contract_id: UUID | None
+) -> str | None:
+    """Why a connection to ``organisation`` must not serve ``contract_id``, or None.
+
+    One process holds every connected Organisation's credentials, harness roots and
+    Workspaces, so a task delivered in one Organisation's namespace is served only under a
+    Contract the ack places in that Organisation. Only the ack can say whose a Contract is:
+    one it does not name, or names without an Organisation, is refused too.
+    """
+
+    served = next((term for term in terms if term.contract_id == contract_id), None)
+    if served is None or served.organisation_id is None:
+        return "contract_not_served"
+    if served.organisation_id != organisation:
+        return "contract_of_another_organisation"
+    return None
+
+
+class MachineSlots:
+    """The machine's one concurrency limit, counted across every connection's Worker.
+
+    Mutated from Temporal's callbacks, which need not run on the event loop's thread, so
+    the counts sit behind a lock and a waiting reservation is woken thread-safely.
+    """
+
+    def __init__(self, limit: int) -> None:
+        self.limit = limit
+        self._used = 0
+        self._lock = threading.Lock()
+        self._waiters: set[tuple[asyncio.AbstractEventLoop, asyncio.Event]] = set()
+
+    @property
+    def used(self) -> int:
+        return self._used
+
+    def connection(self) -> ConnectionSlots:
+        return ConnectionSlots(self)
+
+    def tuner(self, slots: ConnectionSlots) -> WorkerTuner:
+        """A Worker's tuner: its activity slots from ``slots``. The Runner hosts no
+        workflow, so the other kinds get the smallest fixed supply."""
+
+        return WorkerTuner.create_composite(
+            workflow_supplier=FixedSizeSlotSupplier(1),
+            activity_supplier=slots,
+            local_activity_supplier=FixedSizeSlotSupplier(1),
+            nexus_supplier=FixedSizeSlotSupplier(1),
+        )
+
+    def _try_reserve(self, slots: ConnectionSlots) -> bool:
+        with self._lock:
+            if slots.paused or self._used + slots._reserved >= self.limit:
+                return False
+            slots._reserved += 1
+            return True
+
+    def _mark_used(self, slots: ConnectionSlots) -> None:
+        with self._lock:
+            slots._reserved -= 1
+            self._used += 1
+
+    def _release(self, slots: ConnectionSlots, *, used: bool) -> None:
+        with self._lock:
+            if used:
+                self._used -= 1
+            else:
+                slots._reserved -= 1
+        self._wake()
+
+    def _wake(self) -> None:
+        with self._lock:
+            waiters = list(self._waiters)
+        for loop, event in waiters:
+            with contextlib.suppress(RuntimeError):  # a loop already closed waits for nothing
+                loop.call_soon_threadsafe(event.set)
+
+    async def _reserve(self, slots: ConnectionSlots) -> None:
+        waiter = (asyncio.get_running_loop(), asyncio.Event())
+        with self._lock:
+            self._waiters.add(waiter)
+        try:
+            while not self._try_reserve(slots):
+                await waiter[1].wait()
+                waiter[1].clear()
+        finally:
+            with self._lock:
+                self._waiters.discard(waiter)
+
+
+class _Permit(SlotPermit):
+    def __init__(self) -> None:
+        self.used = False
+
+
+class ConnectionSlots(CustomSlotSupplier):
+    """One connection's Worker's activity slots, drawn from the machine's."""
+
+    def __init__(self, machine: MachineSlots) -> None:
+        self._machine = machine
+        self._reserved = 0
+        self._paused = False
+
+    @property
+    def paused(self) -> bool:
+        return self._paused
+
+    @paused.setter
+    def paused(self, value: bool) -> None:
+        self._paused = value
+        self._machine._wake()
+
+    async def reserve_slot(self, ctx: SlotReserveContext) -> SlotPermit:
+        await self._machine._reserve(self)
+        return _Permit()
+
+    def try_reserve_slot(self, ctx: SlotReserveContext) -> SlotPermit | None:
+        return _Permit() if self._machine._try_reserve(self) else None
+
+    def mark_slot_used(self, ctx: SlotMarkUsedContext) -> None:
+        permit = ctx.permit
+        if isinstance(permit, _Permit) and not permit.used:
+            permit.used = True
+            self._machine._mark_used(self)
+
+    def release_slot(self, ctx: SlotReleaseContext) -> None:
+        permit = ctx.permit
+        self._machine._release(self, used=isinstance(permit, _Permit) and permit.used)
+
+
+class GracefulWorker(Protocol):
+    async def run(self) -> None: ...
+    async def shutdown(self) -> None: ...
+
+
+class TemporalClient(Protocol):
+    api_key: str | None
+
+
+# Opens a Temporal client for one namespace with one Runner Token.
+ConnectClient = Callable[[str, str], Awaitable[TemporalClient]]
+# Builds one connection's Worker from its client, the connection and its slot supplier.
+BuildWorker = Callable[[TemporalClient, RunnerConnection, ConnectionSlots], GracefulWorker]
+
+
+@dataclass
+class _Running:
+    connection: RunnerConnection
+    client: TemporalClient
+    slots: ConnectionSlots
+    worker: GracefulWorker
+    task: asyncio.Task[None]
+
+
+@dataclass
+class ConnectionWorkers:
+    """The Workers this Runner runs, one per connection the last ack named.
+
+    :meth:`reconcile` starts a Worker for a new connection, hands a renewed Runner Token to
+    a running one's client, pauses or resumes it, and drains one whose connection is gone:
+    it stops polling and lets what it runs finish, as a SIGTERM drains the process.
+    """
+
+    machine: MachineSlots
+    connect_client: ConnectClient
+    build_worker: BuildWorker
+    _running: dict[UUID, _Running] = field(default_factory=dict)
+    _draining: set[asyncio.Task[None]] = field(default_factory=set)
+    failed: asyncio.Event = field(default_factory=asyncio.Event)
+    error: BaseException | None = None
+    _closed: bool = False
+
+    @property
+    def polled(self) -> Mapping[UUID, RunnerConnection]:
+        return {key: running.connection for key, running in self._running.items()}
+
+    async def reconcile(self, connections: Sequence[RunnerConnection]) -> None:
+        """Follow one ack. A connection that cannot open is logged and retried on the next
+        beat; it never holds back the others, whose tokens must keep being renewed."""
+
+        if self._closed:
+            # Beats go on through a drain; their acks start nothing new.
+            return
+        wanted = {connection.organisation_id: connection for connection in connections}
+        for key in set(self._running) - set(wanted):
+            self._drain(key)
+        for key, connection in wanted.items():
+            if (running := self._running.get(key)) is not None:
+                self._update(running, connection)
+        for key, connection in wanted.items():
+            # A connection's first ack always carries its token; one that did not is retried
+            # on the next beat rather than dialled without one.
+            if key not in self._running and connection.runner_token is not None:
+                try:
+                    await self._start(connection)
+                except Exception as error:  # noqa: BLE001 - retried on the next beat
+                    _logger.warning("cannot poll %s yet: %s", connection.temporal_namespace, error)
+
+    def _update(self, running: _Running, connection: RunnerConnection) -> None:
+        if connection.runner_token is not None and (
+            connection.runner_token != running.client.api_key
+        ):
+            running.client.api_key = connection.runner_token
+        if connection.paused != running.slots.paused:
+            running.slots.paused = connection.paused
+        running.connection = connection
+
+    async def shutdown(self) -> None:
+        """Drain every Worker; returns once each has finished what it was running."""
+
+        self._closed = True
+        for key in list(self._running):
+            self._drain(key)
+        if self._draining:
+            await asyncio.gather(*self._draining)
+
+    async def _start(self, connection: RunnerConnection) -> None:
+        assert connection.runner_token is not None
+        client = await self.connect_client(connection.temporal_namespace, connection.runner_token)
+        if self._closed:
+            # Shut down while the client opened: a Worker started now would never drain.
+            return
+        slots = self.machine.connection()
+        slots.paused = connection.paused
+        worker = self.build_worker(client, connection, slots)
+        task = asyncio.create_task(worker.run())
+        task.add_done_callback(self._watch)
+        self._running[connection.organisation_id] = _Running(
+            connection=connection, client=client, slots=slots, worker=worker, task=task
+        )
+        _logger.info("polling %s in %s", connection.task_queue, connection.temporal_namespace)
+
+    def _drain(self, key: UUID) -> None:
+        running = self._running.pop(key)
+        _logger.info("draining %s: its connection is gone", running.connection.temporal_namespace)
+
+        async def drain() -> None:
+            await running.worker.shutdown()
+            try:
+                await running.task
+            except Exception:
+                # Gone already, so nothing waits on it; the drain is still the process's
+                # own, and the reason must reach its log.
+                _logger.exception(
+                    "the Worker for %s failed while draining", running.connection.temporal_namespace
+                )
+
+        task = asyncio.create_task(drain())
+        self._draining.add(task)
+        task.add_done_callback(self._draining.discard)
+
+    def _watch(self, task: asyncio.Task[Any]) -> None:
+        # A Worker that stops on its own -- not drained -- ends the process, as the one
+        # Worker's `run()` returning or raising did before connections.
+        if task.cancelled() or all(r.task is not task for r in self._running.values()):
+            return
+        self.error = task.exception()
+        self.failed.set()