agentic-runner 3.28.1__tar.gz → 3.30.0__tar.gz

{agentic_runner-3.28.1 → agentic_runner-3.30.0}/PKG-INFO

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

{agentic_runner-3.28.1 → agentic_runner-3.30.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.28.1",
+  "agentic-runner-contracts==3.30.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.28.1 → agentic_runner-3.30.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.28.1"
+__version__ = "3.30.0"
 
 __all__ = ["__version__"]

{agentic_runner-3.28.1 → agentic_runner-3.30.0}/src/agentic_runner/cli.py

@@ -11,7 +11,7 @@ namespace and queue this process was assigned. It is idempotent by state file --
 restart re-reads what is already there rather than registering a second Runner against
 the Organisation's cap.
 
-``install | start | stop | status <name>``, ``credential set`` and ``list`` are the
+``install | start | stop | restart | status <name>``, ``credential set`` and ``list`` are the
 workstation Runner (PRD issue 47, ``workstation.py``): one login agent per Runner, managed
 by the user who hosts it, with no ``sudo`` anywhere. ``<name>`` is the Runner's, the one the
 console lists it under (QTS-1773); a machine with one Runner needs none (QTS-1774).
@@ -215,6 +215,17 @@ def main(argv: Sequence[str] | None = None) -> int:
         driven.add_argument("name", nargs="?", help=_INSTALLED_NAME_HELP)
         driven.add_argument("--root", default=None, type=Path)
 
+    restart = subcommands.add_parser(
+        "restart",
+        help="restart running workstation Runners on the agentic-runner installed now, as "
+        "after `uv tool upgrade`",
+    )
+    restart.add_argument("name", nargs="?", help=_INSTALLED_NAME_HELP)
+    which = restart.add_mutually_exclusive_group()
+    which.add_argument("--name", dest="name_flag", default=None, help=_INSTALLED_NAME_HELP)
+    which.add_argument("--all", action="store_true", help="every Runner running on this machine")
+    restart.add_argument("--root", default=None, type=Path)
+
     listed = subcommands.add_parser(
         "list", help="the workstation Runners installed on this machine, and which are running"
     )
@@ -368,6 +379,8 @@ def main(argv: Sequence[str] | None = None) -> int:
         return asyncio.run(service.run(attestation=_image_attestation(), install=_run_install()))
     if arguments.command in {"install", "start", "stop", "credential"}:
         return _workstation(arguments)
+    if arguments.command == "restart":
+        return _restart(arguments)
     if arguments.command == "list":
         for line in workstation.list_lines(arguments.root or workstation.default_root()):
             print(line)
@@ -462,6 +475,49 @@ def _workstation(arguments: argparse.Namespace) -> int:
         return 1
 
 
+def _restart(arguments: argparse.Namespace) -> int:
+    """``restart <name> | --name <name> | --all``: exit 2 names the Runners installed here.
+
+    A stopped Runner is not started: it was stopped on purpose, and ``systemctl restart``
+    would start it where ``launchctl kickstart`` refuses to, so the two OSes would differ.
+    """
+
+    root = arguments.root or workstation.default_root()
+    name = arguments.name or arguments.name_flag
+    if arguments.all and name:
+        print("restart takes a name or --all, not both", file=sys.stderr)
+        return 2
+    try:
+        if arguments.all:
+            targets = [
+                workstation.RunnerPaths(root=root, name=installed)
+                for installed in workstation.installed_names(root)
+            ]
+            if not targets:
+                raise ValueError(f"no workstation Runner is installed under {root}")
+        elif name:
+            targets = [workstation.installed_runner(root, name)]
+        else:
+            targets = [workstation.only_runner(root, how="name one, or restart --all")]
+    except ValueError as error:
+        print(error, file=sys.stderr)
+        return 2
+    failed = False
+    for paths in targets:
+        if workstation.process_id(paths) is None:
+            print(f"{paths.name} is stopped; `agentic-runner start {paths.name}` starts it")
+            failed = failed or not arguments.all
+            continue
+        try:
+            pid, version = workstation.restart(paths)
+        except (FileNotFoundError, RuntimeError) as error:
+            print(f"{paths.name}: restart failed: {error}", file=sys.stderr)
+            failed = True
+            continue
+        print(f"restarted {paths.name}: pid {pid}, agentic-runner {version}")
+    return 1 if failed else 0
+
+
 def _image_attestation() -> HostAttestation:
     """What a container Runner says about itself, where issue 47 gave the workstation its
     own: the CLIs it found are what the registry serves and routing matches on."""

agentic_runner-3.30.0/src/agentic_runner/organisation_name.py

@@ -0,0 +1,30 @@
+"""The Organisation this Runner serves, by the name the last heartbeat ack gave (QTS-1909).
+
+``agentic-runner list`` is a separate process and reads it from this file, which the
+running Runner rewrites whenever an ack changes it. Absent while the control plane names
+no Organisation -- one below contracts 3.29 -- so ``list`` shows the id instead.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Final
+
+from agentic_runner.private_state import private_read, private_write
+
+__all__ = ["ORGANISATION_NAME_FILENAME", "load_organisation_name", "save_organisation_name"]
+
+ORGANISATION_NAME_FILENAME: Final[str] = "organisation-name"
+
+
+def save_organisation_name(state_dir: Path, name: str | None) -> None:
+    path = state_dir / ORGANISATION_NAME_FILENAME
+    if name is None:
+        path.unlink(missing_ok=True)
+    else:
+        private_write(path, name.encode("utf-8"))
+
+
+def load_organisation_name(state_dir: Path) -> str | None:
+    raw = private_read(state_dir / ORGANISATION_NAME_FILENAME)
+    return None if raw is None else raw.decode("utf-8", errors="replace")

{agentic_runner-3.28.1 → agentic_runner-3.30.0}/src/agentic_runner/service.py

@@ -33,7 +33,7 @@ from collections.abc import AsyncIterator, Awaitable, Callable, Mapping, Sequenc
 from dataclasses import dataclass, field
 from datetime import UTC, datetime, timedelta
 from pathlib import Path
-from typing import Any, Final, Protocol
+from typing import Any, Final, Literal, Protocol
 from uuid import UUID
 
 import httpx
@@ -85,6 +85,7 @@ 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.organisation_name import save_organisation_name
 from agentic_runner.pool_key import (
     POOL_KEY_ENV,
     POOL_KEY_FILENAME,
@@ -852,6 +853,9 @@ class ControlPlaneStream:
     # QTS-1773: the control plane's contracts version, from its ack; None until an ack from
     # one on 3.27 or later, the first to send it and to parse `RunnerInstall.name`.
     _control_plane_contracts: str | None = None
+    # QTS-1909: the name in the copy `list` reads, None while there is none. "unwritten"
+    # until this process first writes it, so the first ack replaces what a previous one left.
+    _organisation_name: str | None | Literal["unwritten"] = "unwritten"
     _last_seen: tuple[float, datetime] | None = None
 
     def _observe_sleep(self, now: datetime) -> None:
@@ -1081,6 +1085,7 @@ class ControlPlaneStream:
         self._take_pool(ack.pool)
         if ack.contracts_version is not None:
             self._control_plane_contracts = ack.contracts_version
+        self._take_organisation_name(ack.organisation_name)
         await self._sync_llm_slots()
         if ack.runner_token is not None:
             self.runner_token = ack.runner_token
@@ -1139,6 +1144,15 @@ class ControlPlaneStream:
         if self.state_dir is not None:
             save_llm_contracts(self.state_dir, terms)
 
+    def _take_organisation_name(self, name: str | None) -> None:
+        """Keep the copy ``list`` reads when the ack's name changes. Unlike the Contract
+        terms, an ack without one clears it: only the name, never the id, can go stale."""
+
+        if self.state_dir is None or name == self._organisation_name:
+            return
+        save_organisation_name(self.state_dir, name)
+        self._organisation_name = name
+
     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."""
@@ -1287,14 +1301,17 @@ async def sign_in(which: str | None, *, store: KeyStore, method: str = OAUTH_TOK
         can = can_separate_uids()
         try:
             require_isolation_supported(mode, can_separate_uids=can)
+            # `run` gives the settings this default; a sign-in must build the same ones, or a
+            # workstation, whose environment sets only the control plane, is refused (QTS-2157).
+            _default_callback_url(os.environ.get(CONTROL_PLANE_ENV, "").strip())
             settings = get_worker_settings()
         except RunnerRegistrationError as error:
             print(f"refusing to sign in ({error.reason}): {error}", file=sys.stderr)
             return 1
-        except ValidationError:
+        except ValidationError as error:
             print(
-                "refusing to sign in: run this with the Runner's environment (`docker exec`, "
-                "`kubectl exec`, or on the workstation that runs it)",
+                f"refusing to sign in: {_invalid_settings(error)}; run this with the Runner's "
+                "environment (`docker exec`, `kubectl exec`, or on the workstation that runs it)",
                 file=sys.stderr,
             )
             return 2
@@ -1322,6 +1339,22 @@ async def sign_in(which: str | None, *, store: KeyStore, method: str = OAUTH_TOK
 _SIGN_IN_CLIS: Final[Mapping[str, str]] = {"claude_code": "claude", "codex_cli": "codex"}
 
 
+def _default_callback_url(control_plane: str) -> None:
+    # The control plane the activities call back is the one this process registered
+    # with, unless the operator points them at an internal address explicitly.
+    if control_plane:
+        os.environ.setdefault("INTERNAL_FASTAPI_BASE_URL", control_plane)
+
+
+def _invalid_settings(error: ValidationError) -> str:
+    """``INTERNAL_FASTAPI_BASE_URL (Field required)``, one per field, never the value."""
+
+    return ", ".join(
+        f"{'.'.join(str(part) for part in detail['loc'])} ({detail['msg']})"
+        for detail in error.errors(include_input=False, include_url=False)
+    )
+
+
 async def run(
     *,
     http_client: httpx.AsyncClient | None = None,
@@ -1402,9 +1435,7 @@ async def _run(
     except (RunnerRegistrationError, UnsafeStateError) as error:
         print(f"refusing to start ({error.reason}): {error}", flush=True)
         return 1
-    # The control plane the activities call back is the one this process registered
-    # with, unless the operator points them at an internal address explicitly.
-    os.environ.setdefault("INTERNAL_FASTAPI_BASE_URL", control_plane)
+    _default_callback_url(control_plane)
     settings = get_worker_settings()
     try:
         attestation = with_profile_acp_cli_kinds(with_acp_bridges(attestation, settings), settings)

{agentic_runner-3.28.1 → agentic_runner-3.30.0}/src/agentic_runner/workstation.py

@@ -1,7 +1,7 @@
 """The workstation Runner: one login agent per Runner (PRD issue 47, map ticket 23).
 
-``agentic-runner install | start | stop | status <name>`` and ``list``. Everything a CI-runner
-precedent does on a developer machine and nothing a daemon would need:
+``agentic-runner install | start | stop | restart | status <name>`` and ``list``. Everything
+a CI-runner precedent does on a developer machine and nothing a daemon would need:
 
 * **One process per Runner** (23 item 3), each with its own state directory, identity,
   namespace, Runner Token, hooks, credential store and Workspaces under ``<root>/<name>/``.
@@ -37,11 +37,12 @@ import shutil
 import subprocess
 import sys
 import tempfile
+import time
 from collections.abc import Callable, Mapping, Sequence
 from dataclasses import dataclass
 from datetime import UTC, datetime
 from pathlib import Path
-from typing import Any, Final
+from typing import Any, Final, Literal
 from xml.sax.saxutils import escape
 
 import httpx
@@ -55,6 +56,7 @@ 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.llm_contracts import load_llm_contracts
+from agentic_runner.organisation_name import load_organisation_name
 from agentic_runner.pool_key import parse_pool_key, save_pool_key
 from agentic_runner.private_state import UnsafeStateError
 from agentic_runner.registration import load_state
@@ -64,6 +66,7 @@ from agentic_runner_contracts.public_metadata import NAMESPACE_PREFIX
 from agentic_runner_contracts.runner_registration import (
     RUNNER_NAME_PATTERN,
     CliVersion,
+    ContractLlmTerms,
     EgressPosture,
     HostAttestation,
     InstallChannel,
@@ -89,11 +92,13 @@ __all__ = [
     "install",
     "install_channel",
     "installed_names",
+    "installed_runner",
     "list_lines",
     "locate_clis",
     "only_runner",
     "parse_acp_cli_kinds",
     "require_any_cli",
+    "restart",
     "run_environment",
     "run_process",
     "service_definition",
@@ -156,6 +161,16 @@ def installed_names(root: Path) -> list[str]:
     )
 
 
+def installed_runner(root: Path, name: str) -> RunnerPaths:
+    """``<name>``, refused with the names installed here when it is not one of them."""
+
+    names = installed_names(root)
+    if name in names:
+        return RunnerPaths(root=root, name=name)
+    installed = ", ".join(names) if names else "none"
+    raise ValueError(f"no Runner named {name!r} is installed under {root}; installed: {installed}")
+
+
 def only_runner(root: Path, *, how: str = "name one") -> RunnerPaths:
     """The one Runner installed here, so a command needs no name (QTS-1774)."""
 
@@ -442,6 +457,7 @@ class ServiceDefinition:
     install: list[list[str]]
     start: list[list[str]]
     stop: list[list[str]]
+    restart: list[list[str]]
 
 
 def runner_command(name: str, root: Path) -> list[str]:
@@ -502,6 +518,9 @@ def _launch_agent(
         install=[],
         start=[["launchctl", "bootstrap", domain, str(plist)]],
         stop=[["launchctl", "bootout", f"{domain}/{name}"]],
+        # One call, not bootout then bootstrap: launchd refuses a bootstrap of a label it
+        # still holds, and it holds it until the old process has drained.
+        restart=[["launchctl", "kickstart", "-k", f"{domain}/{name}"]],
     )
 
 
@@ -544,6 +563,7 @@ def _systemd_user_unit(
         ],
         start=[[*systemctl, "enable", "--now", unit_name]],
         stop=[[*systemctl, "disable", "--now", unit_name]],
+        restart=[[*systemctl, "restart", unit_name]],
     )
 
 
@@ -597,6 +617,10 @@ def _logon_task(
             ["schtasks", "/End", "/TN", task_name],
             ["schtasks", "/Change", "/TN", task_name, "/DISABLE"],
         ],
+        restart=[
+            ["schtasks", "/End", "/TN", task_name],
+            ["schtasks", "/Run", "/TN", task_name],
+        ],
     )
 
 
@@ -670,9 +694,9 @@ _LIST_HEADER: Final = (
 def list_lines(root: Path) -> list[str]:
     """``list``: one row per Runner installed here (QTS-1774).
 
-    Ids, not names: the Runner is told neither the Organisation's nor the Contract's name.
-    Eight characters, as the console shows a Runner's id beside its name (Spec: Runners
-    rev 7).
+    The Organisation's and the Contract's names once an ack from a control plane on 3.29
+    named them (QTS-1909); before that, the first eight characters of their ids, as the
+    console shows a Runner's id beside its name (Spec: Runners rev 7).
     """
 
     names = installed_names(root)
@@ -705,17 +729,21 @@ def _list_row_or_reason(paths: RunnerPaths) -> tuple[str, str, str, str, str, st
 def _list_row(paths: RunnerPaths) -> tuple[str, str, str, str, str, str]:
     state = load_state(paths.state_dir)
     contracts = load_llm_contracts(paths.state_dir)
+    organisation_name = _printable(load_organisation_name(paths.state_dir))
     try:
         version = paths.started_version.read_text(encoding="utf-8").strip() or "-"
     except OSError:
         version = "-"
     return (
         paths.name,
-        state.temporal_namespace.removeprefix(NAMESPACE_PREFIX)[:8] if state else "-",
+        (
+            organisation_name
+            or (state.temporal_namespace.removeprefix(NAMESPACE_PREFIX)[:8] if state else "-")
+        ),
         (
             "-"
             if not contracts
-            else str(contracts[0].contract_id)[:8]
+            else _contract_label(contracts[0])
             if len(contracts) == 1
             else f"{len(contracts)} Contracts"
         ),
@@ -725,6 +753,15 @@ def _list_row(paths: RunnerPaths) -> tuple[str, str, str, str, str, str]:
     )
 
 
+def _contract_label(terms: ContractLlmTerms) -> str:
+    return _printable(terms.contract_name) or str(terms.contract_id)[:8]
+
+
+def _printable(name: str | None) -> str:
+    # A name someone typed in the console: an escape sequence in it would reach the terminal.
+    return "".join(character for character in name or "" if character.isprintable())
+
+
 def next_step_lines(host_party: str) -> list[str]:
     """Where to go once the Runner is live (QTS-1314): the dogfood install ended at
     ``started`` and left the person with no idea what the console wanted next.
@@ -822,9 +859,36 @@ def stop(paths: RunnerPaths, **driver: Any) -> None:
     _drive_service(paths, "stop", **driver)
 
 
+def restart(
+    paths: RunnerPaths,
+    *,
+    timeout: float = 60.0,
+    sleep: Callable[[float], None] = time.sleep,
+    clock: Callable[[], float] = time.monotonic,
+    **driver: Any,
+) -> tuple[int, str]:
+    """Restart a running Runner and wait for its new process: ``(pid, version)``.
+
+    ``uv tool upgrade`` replaces the console script, not the process, so a login agent keeps
+    running the old version until this (QTS-2158). The process writes its version before
+    its pidfile, so a new pid means the version beside it is the new process's.
+    """
+
+    previous = process_id(paths)
+    _drive_service(paths, "restart", **driver)
+    deadline = clock() + timeout
+    while (pid := process_id(paths)) is None or pid == previous:
+        if clock() >= deadline:
+            raise RuntimeError(
+                f"no new process wrote {paths.pidfile} within {timeout:.0f}s; see {paths.log}"
+            )
+        sleep(0.5)
+    return pid, paths.started_version.read_text(encoding="utf-8").strip()
+
+
 def _drive_service(
     paths: RunnerPaths,
-    verb: str,
+    verb: Literal["start", "stop", "restart"],
     *,
     platform: str = sys.platform,
     home: Path | None = None,
@@ -832,7 +896,7 @@ def _drive_service(
 ) -> None:
     settings = WorkstationSettings.load(paths)
     definition = service_definition(paths, settings, platform=platform, home=home)
-    drive(definition.start if verb == "start" else definition.stop, run=run)
+    drive(getattr(definition, verb), run=run)
 
 
 def run_process(paths: RunnerPaths, *, login_agent: bool) -> int: