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

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

@@ -1,11 +1,11 @@
 Metadata-Version: 2.5
 Name: agentic-runner
-Version: 3.27.0
+Version: 3.28.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.27.0
+Requires-Dist: agentic-runner-contracts==3.28.1
 Requires-Dist: cryptography<51,>=50
 Requires-Dist: httpx<1.0,>=0.27
 Requires-Dist: pydantic-settings<3.0,>=2.0
@@ -47,7 +47,8 @@ root: Python, git, `codex`, `claude`, nothing else) and installs with
 `charts/agentic-runner`.
 
 On a workstation it is a per-user login agent, one per Runner:
-`agentic-runner install | start | stop | status <name>` (LaunchAgent, systemd user unit or
-logon task; never `sudo`), with Credential References in the OS credential store.
+`agentic-runner install | start | stop | status <name>` and `agentic-runner list`
+(LaunchAgent, systemd user unit or logon task; never `sudo`), with Credential References in
+the OS credential store.
 
 Licensed under AGPL-3.0-only.

{agentic_runner-3.27.0 → agentic_runner-3.28.1}/README.md

@@ -28,7 +28,8 @@ root: Python, git, `codex`, `claude`, nothing else) and installs with
 `charts/agentic-runner`.
 
 On a workstation it is a per-user login agent, one per Runner:
-`agentic-runner install | start | stop | status <name>` (LaunchAgent, systemd user unit or
-logon task; never `sudo`), with Credential References in the OS credential store.
+`agentic-runner install | start | stop | status <name>` and `agentic-runner list`
+(LaunchAgent, systemd user unit or logon task; never `sudo`), with Credential References in
+the OS credential store.
 
 Licensed under AGPL-3.0-only.

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

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

@@ -11,10 +11,10 @@ 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>`` and ``credential set`` 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).
+``install | start | stop | 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).
 
 ``sign-in [claude|codex]`` gives a person's own Runner their LLM access: their subscription,
 through the vendor's own sign-in in this terminal, or an API key stored in the Runner's
@@ -107,6 +107,7 @@ _NAME_HELP = (
     "this Runner's name: the console lists it under this name, and every command on this "
     "machine takes it"
 )
+_INSTALLED_NAME_HELP = "the Runner's name; omitted when this machine runs one Runner"
 
 
 def _old_org_flag(parser: argparse.ArgumentParser) -> None:
@@ -211,14 +212,19 @@ def main(argv: Sequence[str] | None = None) -> int:
         driven = subcommands.add_parser(
             service_verb, help=f"{service_verb} one workstation Runner's login agent"
         )
-        driven.add_argument("name", help=_NAME_HELP)
+        driven.add_argument("name", nargs="?", help=_INSTALLED_NAME_HELP)
         driven.add_argument("--root", default=None, type=Path)
 
+    listed = subcommands.add_parser(
+        "list", help="the workstation Runners installed on this machine, and which are running"
+    )
+    listed.add_argument("--root", default=None, type=Path)
+
     credential = subcommands.add_parser(
         "credential", help="install a Credential Reference value into this host's store"
     )
     credential.add_argument("action", choices=("set",))
-    credential.add_argument("name", help=_NAME_HELP)
+    credential.add_argument("name", nargs="?", help=_INSTALLED_NAME_HELP)
     credential.add_argument("reference")
     credential.add_argument("--root", default=None, type=Path)
 
@@ -233,7 +239,7 @@ def main(argv: Sequence[str] | None = None) -> int:
     status = subcommands.add_parser(
         "status", help="print this installation's versions and Recipient Key fingerprint"
     )
-    status.add_argument("name", nargs="?", help="a workstation Runner's name (issue 47)")
+    status.add_argument("name", nargs="?", help=_INSTALLED_NAME_HELP)
     status.add_argument("--root", default=None, type=Path)
 
     sign_in = subcommands.add_parser(
@@ -256,7 +262,7 @@ def main(argv: Sequence[str] | None = None) -> int:
     sign_in.add_argument(
         "--name",
         default=None,
-        help="the workstation Runner's name, when this workstation runs more than one",
+        help="the workstation Runner's name, when this machine runs more than one",
     )
     _old_org_flag(sign_in)
     sign_in.add_argument("--root", default=None, type=Path, help=argparse.SUPPRESS)
@@ -351,9 +357,21 @@ def main(argv: Sequence[str] | None = None) -> int:
             return workstation.run_process(
                 _runner_paths(arguments), login_agent=arguments.login_agent
             )
+        if installed := _installed_instead_of_run():
+            print(
+                f"this machine runs {', '.join(installed)} as login agents: start one with "
+                "`agentic-runner start <name>`. `run` serves a Runner its environment sets "
+                "up, as in a container",
+                file=sys.stderr,
+            )
+            return 2
         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 == "list":
+        for line in workstation.list_lines(arguments.root or workstation.default_root()):
+            print(line)
+        return 0
     if arguments.command == "recipient-key":
         api, kube_ns = in_cluster()
         pair = ensure_recipient_key(
@@ -364,9 +382,17 @@ def main(argv: Sequence[str] | None = None) -> int:
         )
         return 0
     if arguments.command == "status":
-        lines = (
-            workstation.status_lines(_runner_paths(arguments)) if arguments.name else status_lines()
-        )
+        if arguments.name or (
+            not _in_container()
+            and workstation.installed_names(arguments.root or workstation.default_root())
+        ):
+            try:
+                lines = workstation.status_lines(_runner_paths(arguments))
+            except ValueError as error:
+                print(error, file=sys.stderr)
+                return 2
+        else:
+            lines = status_lines()
         for line in lines:
             print(line)
         return 0
@@ -389,16 +415,33 @@ def main(argv: Sequence[str] | None = None) -> int:
     return _callback(arguments)
 
 
-def _runner_paths(arguments: argparse.Namespace) -> workstation.RunnerPaths:
-    return workstation.RunnerPaths(
-        root=arguments.root or workstation.default_root(),
-        name=workstation.validate_name(arguments.name),
-    )
+def _runner_paths(
+    arguments: argparse.Namespace, *, how: str = "name one"
+) -> workstation.RunnerPaths:
+    """``<name>``, or the one Runner this machine runs -- nothing to remember (QTS-1774)."""
+
+    root = arguments.root or workstation.default_root()
+    if not arguments.name:
+        return workstation.only_runner(root, how=how)
+    return workstation.RunnerPaths(root=root, name=workstation.validate_name(arguments.name))
+
+
+def _installed_instead_of_run() -> list[str]:
+    """The Runners installed here, when a bare ``run`` would start none of them.
+
+    An installed Runner is its login agent's process; ``run`` without ``--name`` registers
+    from the environment, and on a workstation that holds neither a token nor an identity
+    it could only fail without saying what to type instead (QTS-1774).
+    """
+
+    if _in_container() or registration_token_from_env() or load_state(_state_dir()):
+        return []
+    return workstation.installed_names(workstation.default_root())
 
 
 def _workstation(arguments: argparse.Namespace) -> int:
-    paths = _runner_paths(arguments)
     try:
+        paths = _runner_paths(arguments)
         if arguments.command == "install":
             return _install(arguments, paths)
         if arguments.command == "start":
@@ -482,7 +525,7 @@ def _sign_in(arguments: argparse.Namespace) -> int:
     store: KeyStore
     if arguments.name or not _in_container():
         try:
-            paths = _sign_in_paths(arguments)
+            paths = _runner_paths(arguments, how="name one with --name")
         except ValueError as error:
             print(error, file=sys.stderr)
             return 2
@@ -495,26 +538,6 @@ def _sign_in(arguments: argparse.Namespace) -> int:
     return asyncio.run(service.sign_in(arguments.runtime, store=store, method=arguments.method))
 
 
-def _sign_in_paths(arguments: argparse.Namespace) -> workstation.RunnerPaths:
-    """``--name``, or the one Runner this workstation runs -- no id to type."""
-
-    if arguments.name:
-        return _runner_paths(arguments)
-    root = arguments.root or workstation.default_root()
-    installed = (
-        sorted(path.name for path in root.iterdir() if (path / "workstation.json").is_file())
-        if root.is_dir()
-        else []
-    )
-    if len(installed) != 1:
-        raise ValueError(
-            "no workstation Runner is installed here"
-            if not installed
-            else f"this workstation runs {', '.join(installed)}: name one with --name"
-        )
-    return workstation.RunnerPaths(root=root, name=installed[0])
-
-
 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.27.0 → agentic_runner-3.28.1}/src/agentic_runner/workstation.py

@@ -1,6 +1,6 @@
 """The workstation Runner: one login agent per Runner (PRD issue 47, map ticket 23).
 
-``agentic-runner install | start | stop | status <name>``. Everything a CI-runner
+``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:
 
 * **One process per Runner** (23 item 3), each with its own state directory, identity,
@@ -47,16 +47,20 @@ from xml.sax.saxutils import escape
 import httpx
 from pydantic import BaseModel, ConfigDict
 
+from agentic_runner import __version__ as runner_version
 from agentic_runner import service
 from agentic_runner.build import build_id
 from agentic_runner.cli_floor import CLI_FLOORS, CLI_NAMES, meets_floor, parse_cli_version
 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.pool_key import parse_pool_key, save_pool_key
+from agentic_runner.private_state import UnsafeStateError
 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
+from agentic_runner_contracts.public_metadata import NAMESPACE_PREFIX
 from agentic_runner_contracts.runner_registration import (
     RUNNER_NAME_PATTERN,
     CliVersion,
@@ -84,7 +88,10 @@ __all__ = [
     "default_root",
     "install",
     "install_channel",
+    "installed_names",
+    "list_lines",
     "locate_clis",
+    "only_runner",
     "parse_acp_cli_kinds",
     "require_any_cli",
     "run_environment",
@@ -132,6 +139,36 @@ def default_root(*, platform: str = sys.platform, environ: Mapping[str, str] = o
     return (Path(state_home) if state_home else home / ".local" / "state") / "agentic-runner"
 
 
+def installed_names(root: Path) -> list[str]:
+    """Every Runner installed under ``root``, by name.
+
+    A directory whose name is not a Runner's is skipped: the guide moves an old install
+    aside as ``<name>.organisation`` before a new token, and that one is not a Runner here.
+    """
+
+    if not root.is_dir():
+        return []
+    return sorted(
+        path.name
+        for path in root.iterdir()
+        if re.fullmatch(RUNNER_NAME_PATTERN, path.name)
+        and RunnerPaths(root=root, name=path.name).settings_file.is_file()
+    )
+
+
+def only_runner(root: Path, *, how: str = "name one") -> RunnerPaths:
+    """The one Runner installed here, so a command needs no name (QTS-1774)."""
+
+    names = installed_names(root)
+    if len(names) == 1:
+        return RunnerPaths(root=root, name=names[0])
+    if not names:
+        raise ValueError(f"no workstation Runner is installed under {root}")
+    raise ValueError(
+        f"this machine runs {', '.join(names)}: {how} (`agentic-runner list` shows each)"
+    )
+
+
 @dataclass(frozen=True)
 class RunnerPaths:
     """``<root>/<name>/`` and everything the process keeps under it."""
@@ -184,6 +221,12 @@ class RunnerPaths:
     def log(self) -> Path:
         return self.state_dir / "runner.log"
 
+    @property
+    def started_version(self) -> Path:
+        # Written by the process, not `install`: every Runner here runs one console script,
+        # and after `uv tool upgrade` a Runner not restarted still runs the old version.
+        return self.state_dir / "runner-version"
+
     @property
     def socket_dir(self) -> Path:
         # `sun_path` is ~104 bytes and "~/Library/Application Support/..." is most of
@@ -614,6 +657,74 @@ def status_lines(paths: RunnerPaths, *, now: datetime | None = None) -> list[str
     return lines
 
 
+_LIST_HEADER: Final = (
+    "NAME",
+    "ORGANISATION",
+    "CONTRACT",
+    "CONTROL PLANE",
+    "VERSION",
+    "LOGIN AGENT",
+)
+
+
+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).
+    """
+
+    names = installed_names(root)
+    if not names:
+        return [f"no workstation Runner is installed under {root}"]
+    rows = [
+        _LIST_HEADER,
+        *(_list_row_or_reason(RunnerPaths(root=root, name=name)) for name in names),
+    ]
+    widths = [max(len(row[column]) for row in rows) for column in range(len(_LIST_HEADER) - 1)]
+    return [
+        "  ".join([*(cell.ljust(width) for cell, width in zip(row, widths, strict=False)), row[-1]])
+        for row in rows
+    ]
+
+
+def _list_row_or_reason(paths: RunnerPaths) -> tuple[str, str, str, str, str, str]:
+    """One install that cannot be read must not hide the others' rows (QTS-1910).
+
+    The first line only: a pydantic error runs to one line per field, and the row is one.
+    """
+
+    try:
+        return _list_row(paths)
+    except (OSError, ValueError, UnsafeStateError) as error:
+        reason = str(error).splitlines()[0] if str(error) else type(error).__name__
+        return (paths.name, "-", "-", "-", "-", f"unreadable: {reason}")
+
+
+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)
+    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 "-",
+        (
+            "-"
+            if not contracts
+            else str(contracts[0].contract_id)[:8]
+            if len(contracts) == 1
+            else f"{len(contracts)} Contracts"
+        ),
+        WorkstationSettings.load(paths).control_plane_url,
+        version,
+        "running" if process_id(paths) else "stopped",
+    )
+
+
 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.
@@ -735,6 +846,7 @@ def run_process(paths: RunnerPaths, *, login_agent: bool) -> int:
         return 1
     for name, value in run_environment(paths, settings).items():
         os.environ[name] = value
+    paths.started_version.write_text(runner_version, encoding="utf-8")
     store = open_workstation_store(paths.name, fallback=paths.credentials)
     attestation = collect_attestation(
         channel=settings.install_channel,