agentic-runner 3.17.0__tar.gz → 3.18.1__tar.gz

{agentic_runner-3.17.0 → agentic_runner-3.18.1}/PKG-INFO

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

{agentic_runner-3.17.0 → agentic_runner-3.18.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.17.0",
+  "agentic-runner-contracts==3.18.1",
   # Imported directly by `registration.py` (the Ed25519 identity that signs every
   # heartbeat); already present transitively through pyjwt[crypto], declared because
   # we import it.
@@ -31,7 +31,7 @@ testing = [
 ]
 
 [project.scripts]
-agentic-runner = "agentic_runner.cli:main"
+agentic-runner = "agentic_runner.launch:main"
 
 [project.entry-points.pytest11]
 agentic_runner = "agentic_runner.testing.plugin"

{agentic_runner-3.17.0 → agentic_runner-3.18.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.17.0"
+__version__ = "3.18.1"
 
 __all__ = ["__version__"]

{agentic_runner-3.17.0 → agentic_runner-3.18.1}/src/agentic_runner/cli.py

@@ -13,7 +13,8 @@ the Organisation's cap.
 
 ``install | start | stop | status <org>`` and ``credential set`` are the workstation
 Runner (PRD issue 47, ``workstation.py``): one login agent per Organisation, managed by
-the user who hosts it, with no ``sudo`` anywhere.
+the user who hosts it, with no ``sudo`` anywhere. ``add <name>`` registers another Runner
+beside them, reusing their control plane and ``PATH`` (ADR-0022 §21).
 
 ``sign-in --contract <id>`` signs one Contract's Claude Code in with Anthropic's own flow,
 in this terminal, as that Contract's uid in its harness root (QTS-1448). No code or token
@@ -179,6 +180,21 @@ 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)")
+
+    add = subcommands.add_parser(
+        "add",
+        help="register another Runner under this install, with its own process, identity "
+        "and Recipient Key (one per Contract)",
+    )
+    add.add_argument("org", metavar="name", help="the new Runner's name on this machine")
+    add.add_argument(
+        "--beside",
+        default=None,
+        help="the installed Runner whose control plane and PATH to reuse; needed only when "
+        "the installed Runners talk to different control planes",
+    )
+    add.add_argument("--no-start", action="store_true", help="write the agent, do not start")
+    add.add_argument("--root", default=None, type=Path, help="state root (default per OS)")
     for service_verb in ("start", "stop"):
         driven = subcommands.add_parser(
             service_verb, help=f"{service_verb} one Organisation's login agent"
@@ -312,7 +328,7 @@ def main(argv: Sequence[str] | None = None) -> int:
         if arguments.org:
             return workstation.run_process(_org_paths(arguments), login_agent=arguments.login_agent)
         return asyncio.run(service.run(attestation=_image_attestation()))
-    if arguments.command in {"install", "start", "stop", "credential"}:
+    if arguments.command in {"install", "add", "start", "stop", "credential"}:
         return _workstation(arguments)
     if arguments.command == "recipient-key":
         api, kube_ns = in_cluster()
@@ -359,6 +375,8 @@ def _workstation(arguments: argparse.Namespace) -> int:
     try:
         if arguments.command == "install":
             return _install(arguments, paths)
+        if arguments.command == "add":
+            return _add(arguments, paths)
         if arguments.command == "start":
             workstation.start(paths)
             print(f"started {paths.org}")
@@ -422,11 +440,7 @@ def _install(arguments: argparse.Namespace, paths: workstation.OrgPaths) -> int:
     except ValueError as error:
         print(str(error), file=sys.stderr)
         return 2
-    # Pasted, never a flag: a flag is in the process table for every uid on the box.
-    token = registration_token_from_env() or getpass.getpass(
-        "Runner Registration Token (yours from /me/runners, or the Organisation Admin's for "
-        "an Organisation Runner): "
-    )
+    token = _registration_token()
     settings = workstation.WorkstationSettings(
         org=paths.org,
         control_plane_url=arguments.control_plane,
@@ -436,11 +450,19 @@ def _install(arguments: argparse.Namespace, paths: workstation.OrgPaths) -> int:
         install_channel=workstation.install_channel(),
         acp_cli_kinds=acp_cli_kinds,
     )
+    return _register(paths, settings, token, start=not arguments.no_start)
+
+
+def _register(
+    paths: workstation.OrgPaths,
+    settings: workstation.WorkstationSettings,
+    token: str,
+    *,
+    start: bool,
+) -> int:
     try:
         lines = asyncio.run(
-            workstation.install(
-                paths, settings, registration_token=token, start_service=not arguments.no_start
-            )
+            workstation.install(paths, settings, registration_token=token, start_service=start)
         )
     except (workstation.CliMissingError, RunnerRegistrationError, RuntimeError) as error:
         print(f"install refused: {error}", file=sys.stderr)
@@ -450,6 +472,19 @@ def _install(arguments: argparse.Namespace, paths: workstation.OrgPaths) -> int:
     return 0
 
 
+def _add(arguments: argparse.Namespace, paths: workstation.OrgPaths) -> int:
+    settings = workstation.settings_to_add(paths, beside=arguments.beside)
+    return _register(paths, settings, _registration_token(), start=not arguments.no_start)
+
+
+def _registration_token() -> str:
+    # Pasted, never a flag: a flag is in the process table for every uid on the box.
+    return registration_token_from_env() or getpass.getpass(
+        "Runner Registration Token (yours from /me/runners, or the Organisation Admin's for "
+        "an Organisation Runner): "
+    )
+
+
 def _acp_cli_kinds(flag: str | None, paths: workstation.OrgPaths) -> str:
     # A reinstall to pick up a new PATH or retry a token must not turn ACP off (QTS-1355).
     if flag is not None:

agentic_runner-3.18.1/src/agentic_runner/launch.py

@@ -0,0 +1,38 @@
+"""The ``agentic-runner`` console script: a SIGTERM disposition before the CLI imports.
+
+Importing the CLI takes seconds (Temporal, httpx, pydantic). In a container the Runner is
+PID 1, and the kernel drops a signal PID 1 has no handler for, so a SIGTERM in that window
+was lost and ``docker stop`` waited out its grace period to SIGKILL (QTS-1536). Nothing
+has run yet, so it exits 0 -- what launchd's ``KeepAlive: SuccessfulExit: false`` reads
+as a clean stop. ``agentic-runner run`` replaces this with its own handler before its
+first await; every other subcommand gets the default disposition back, so a killed
+callback such as ``ask`` never reads as one that succeeded.
+
+Imports nothing but the standard library: anything heavier reopens the window.
+"""
+
+from __future__ import annotations
+
+import os
+import signal
+import sys
+from types import FrameType
+
+
+def main() -> int:
+    signal.signal(signal.SIGTERM, _exit_before_start)
+    from agentic_runner.cli import main as cli_main
+
+    if sys.argv[1:2] != ["run"]:
+        signal.signal(signal.SIGTERM, signal.SIG_DFL)
+    return cli_main()
+
+
+def _exit_before_start(signum: int, frame: FrameType | None) -> None:
+    # Not SystemExit: raised mid-import, it tears down half-initialised modules and the
+    # interpreter prints their errors. Nothing has written state yet to flush or close.
+    os._exit(0)
+
+
+if __name__ == "__main__":  # pragma: no cover - `runner_command`'s fallback without the script
+    raise SystemExit(main())

{agentic_runner-3.17.0 → agentic_runner-3.18.1}/src/agentic_runner/service.py

@@ -27,7 +27,7 @@ import signal
 import sys
 import tempfile
 import time
-from collections.abc import Awaitable, Callable, Mapping, Sequence
+from collections.abc import AsyncIterator, Awaitable, Callable, Mapping, Sequence
 from dataclasses import dataclass, field
 from datetime import UTC, datetime, timedelta
 from pathlib import Path
@@ -558,12 +558,14 @@ async def run_worker_until_terminated(
     Directive is mid-run. The chart's ``preStop`` hook (issue 02) signals termination as
     early as possible; this handler is what turns that into ``Worker.shutdown()`` -- stop
     polling for new work, wait for the in-flight activity, then let ``run()`` return.
+
+    A caller that passes ``stop`` owns SIGTERM already (``run`` installs it before it
+    starts up, QTS-1536); one set before the Worker polls never starts it.
     """
 
-    loop = asyncio.get_running_loop()
-    stop_event = stop or asyncio.Event()
-    loop.add_signal_handler(signal.SIGTERM, stop_event.set)
-    try:
+    if stop is not None and stop.is_set():
+        return
+    async with _sigterm_sets(stop) as stop_event:
         run_task = asyncio.ensure_future(worker.run())
         stop_task = asyncio.ensure_future(stop_event.wait())
         await asyncio.wait({run_task, stop_task}, return_when=asyncio.FIRST_COMPLETED)
@@ -573,10 +575,51 @@ async def run_worker_until_terminated(
             _logger.info("Worker received SIGTERM: draining in-flight activity before exit")
             await worker.shutdown()
         await run_task
+
+
+@contextlib.asynccontextmanager
+async def _sigterm_sets(stop: asyncio.Event | None) -> AsyncIterator[asyncio.Event]:
+    """``stop`` as given, or a new event SIGTERM sets for the length of the block."""
+
+    if stop is not None:
+        yield stop
+        return
+    loop = asyncio.get_running_loop()
+    stop_event = asyncio.Event()
+    loop.add_signal_handler(signal.SIGTERM, stop_event.set)
+    try:
+        yield stop_event
     finally:
         loop.remove_signal_handler(signal.SIGTERM)
 
 
+class _StoppedBeforeStartError(Exception):
+    """SIGTERM (or ``stop``) arrived before the Worker polled: no Directive is in flight."""
+
+
+async def _before_stop[T](awaitable: Awaitable[T], stop: asyncio.Event) -> T:
+    """``awaitable``'s result, unless ``stop`` is set first; then it is cancelled.
+
+    Start-up waits on the network -- registration, the first heartbeat, the Temporal
+    connection -- for as long as the far end takes to answer. A stop during that wait
+    must not wait with it.
+    """
+
+    work = asyncio.ensure_future(awaitable)
+    stopped = asyncio.ensure_future(stop.wait())
+    try:
+        await asyncio.wait({work, stopped}, return_when=asyncio.FIRST_COMPLETED)
+    finally:
+        stopped.cancel()
+        if not work.done():
+            work.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await work
+    if work.cancelled():
+        raise _StoppedBeforeStartError
+    return work.result()
+
+
 # ------------------------------------------------------------------ the stream
 
 
@@ -971,6 +1014,40 @@ async def run(
     it says about itself. ``heartbeat_interval`` defaults to the cadence bootstrap gave.
     """
 
+    loop = asyncio.get_running_loop()
+    # Before the first await: in a container this process is PID 1, and the kernel drops
+    # a signal PID 1 has no handler for, so a SIGTERM during start-up was lost and
+    # `docker stop` waited out its grace period to SIGKILL (QTS-1536).
+    stop = stop or asyncio.Event()
+    loop.add_signal_handler(signal.SIGTERM, stop.set)
+    try:
+        return await _run(
+            stop=stop,
+            http_client=http_client,
+            connect=connect,
+            worker_factory=worker_factory,
+            can_change_uid=can_change_uid,
+            heartbeat_interval=heartbeat_interval,
+            readiness=readiness,
+            host_store=host_store,
+            attestation=attestation,
+        )
+    finally:
+        loop.remove_signal_handler(signal.SIGTERM)
+
+
+async def _run(
+    *,
+    stop: asyncio.Event,
+    http_client: httpx.AsyncClient | None,
+    connect: Connector,
+    worker_factory: WorkerFactory,
+    can_change_uid: bool | None,
+    heartbeat_interval: float | None,
+    readiness: Readiness | None,
+    host_store: HostCredentialStore | None,
+    attestation: HostAttestation | None,
+) -> int:
     install_stop_tolerant_child_watcher(asyncio.get_running_loop())
     config = load_config()
     mode = isolation_mode()
@@ -1094,15 +1171,19 @@ async def _serve(
     http_client: httpx.AsyncClient | None,
     connect: Connector,
     worker_factory: WorkerFactory,
-    stop: asyncio.Event | None,
+    stop: asyncio.Event,
     heartbeat_interval: float | None,
     host_store: HostCredentialStore | None,
     attestation: HostAttestation | None,
 ) -> int:
     try:
-        state, outcome = await register(
-            state_dir=state_dir, can_separate_uids=can_change_uid, client=http_client
+        state, outcome = await _before_stop(
+            register(state_dir=state_dir, can_separate_uids=can_change_uid, client=http_client),
+            stop,
         )
+    except _StoppedBeforeStartError:
+        print("stopped before registration completed", flush=True)
+        return 0
     except RunnerRegistrationError as error:
         print(f"registration refused ({error.reason}): {error}", flush=True)
         if error.refuses_registration_token:
@@ -1148,6 +1229,12 @@ async def _serve(
             attestation=attestation,
             lifecycle=lifecycle,
         )
+    except _StoppedBeforeStartError:
+        # No beat with a 10 s timeout on the way out (`_report_stop`): the control plane
+        # may be what start-up was waiting for. The next start carries the stop.
+        lifecycle.add(LifecycleKind.STOP, datetime.now(UTC))
+        print("stopped before the Worker started", flush=True)
+        return 0
     finally:
         pidfile.unlink(missing_ok=True)
 
@@ -1166,7 +1253,7 @@ async def _serve_registered(
     http_client: httpx.AsyncClient | None,
     connect: Connector,
     worker_factory: WorkerFactory,
-    stop: asyncio.Event | None,
+    stop: asyncio.Event,
     interval: float,
     host_store: HostCredentialStore | None,
     attestation: HostAttestation | None,
@@ -1240,21 +1327,24 @@ async def _serve_registered(
     # none, and the Temporal connection below cannot be opened without it.
     while True:
         try:
-            await link.exchange()
+            await _before_stop(link.exchange(), stop)
             break
+        except _StoppedBeforeStartError:
+            raise
         except Exception as error:  # noqa: BLE001 - keep trying until the control plane answers
             if _revoked(error):
                 return 1
             _logger.warning("heartbeat failed before start: %s", error)
-            if stop is not None and stop.is_set():
-                return 1
-            await asyncio.sleep(interval)
-
-    client = await connect(
-        temporal_address,
-        namespace=state.temporal_namespace,
-        api_key=stream.runner_token,
-        tls=os.environ.get(TEMPORAL_TLS_ENV, "").strip().lower() in {"1", "true", "yes"},
+            await _before_stop(asyncio.sleep(interval), stop)
+
+    client = await _before_stop(
+        connect(
+            temporal_address,
+            namespace=state.temporal_namespace,
+            api_key=stream.runner_token,
+            tls=os.environ.get(TEMPORAL_TLS_ENV, "").strip().lower() in {"1", "true", "yes"},
+        ),
+        stop,
     )
     hooks = build_hook_runner(config)
     async with (
@@ -1289,7 +1379,6 @@ async def _serve_registered(
             graceful_shutdown_timeout=graceful_shutdown_timeout(settings),
             max_concurrent_activities=state.max_concurrent_directives,
         )
-        stop = stop or asyncio.Event()
         revoked = asyncio.Event()
         beat = asyncio.create_task(
             _heartbeat_forever(link, stream, client, interval, stop=stop, revoked=revoked)

{agentic_runner-3.17.0 → agentic_runner-3.18.1}/src/agentic_runner/workstation.py

@@ -7,6 +7,8 @@ precedent does on a developer machine and nothing a daemon would need:
   identity, namespace, Runner Token, hooks, credential store and Workspaces under
   ``<root>/<org>/``. A contractor with two clients runs two. There is no supervisor over
   N Organisations -- that is the "one Runner straddling Organisations" 12 A6 rejected.
+  ``add <name>`` puts another such process beside them, a personal Runner per Contract
+  (ADR-0022 §21), named freely rather than after its Organisation.
 * **A login agent, never a system daemon** (23 item 1): a LaunchAgent in
   ``~/Library/LaunchAgents`` on macOS, a systemd *user* unit (with linger) on Linux, a
   per-user logon task on Windows. No ``sudo`` anywhere: the login keychain is unreachable
@@ -81,6 +83,7 @@ __all__ = [
     "run_environment",
     "run_process",
     "service_definition",
+    "settings_to_add",
     "start",
     "status_lines",
     "stop",
@@ -387,7 +390,7 @@ def runner_command(org: str, root: Path) -> list[str]:
     # The console script as found, not resolved: Homebrew's `bin/agentic-runner` is a
     # symlink into a versioned Cellar path that the next `brew upgrade` deletes.
     script = shutil.which("agentic-runner")
-    prefix = [script] if script else [sys.executable, "-m", "agentic_runner.cli"]
+    prefix = [script] if script else [sys.executable, "-m", "agentic_runner.launch"]
     return [*prefix, "run", "--org", org, "--root", str(root), "--login-agent"]
 
 
@@ -673,6 +676,50 @@ async def install(
     return lines
 
 
+def settings_to_add(paths: OrgPaths, *, beside: str | None) -> WorkstationSettings:
+    """``add <name>``: what ``install`` registers another Runner with (ADR-0022 §21).
+
+    A personal Runner serves one Contract, so a person with three Contracts runs three. Each
+    is ``install``'s own process with its own state directory -- identity, Runner Token and
+    Recipient Key (§37) -- and only the settings an earlier ``install`` was told are copied,
+    so the command the console shows carries no Temporal address.
+    """
+
+    # Registered state, not workstation.json: ``install`` saves the settings before it
+    # registers, so a refused token leaves them behind and the retry must go through.
+    if load_state(paths.state_dir) is not None:
+        raise ValueError(
+            f"{paths.org!r} is already installed under {paths.root}; pick a new name for "
+            "the Runner you are adding"
+        )
+    return _settings_beside(paths.root, beside).model_copy(update={"org": paths.org})
+
+
+def _settings_beside(root: Path, beside: str | None) -> WorkstationSettings:
+    if beside is not None:
+        return WorkstationSettings.load(OrgPaths(root=root, org=validate_org(beside)))
+    installed = [
+        WorkstationSettings.load(OrgPaths(root=root, org=file.parent.name))
+        for file in sorted(root.glob("*/workstation.json"), key=lambda file: file.stat().st_mtime)
+    ]
+    if not installed:
+        raise FileNotFoundError(
+            f"no Runner is installed under {root}; run `agentic-runner install` first"
+        )
+    endpoints = {
+        (settings.control_plane_url, settings.temporal_address, settings.temporal_tls)
+        for settings in installed
+    }
+    if len(endpoints) > 1:
+        names = ", ".join(sorted(settings.org for settings in installed))
+        raise ValueError(
+            f"the Runners under {root} ({names}) talk to different control planes; "
+            "name the one to add beside with --beside"
+        )
+    # The newest install's PATH and ACP kinds: the latest the person told this machine.
+    return installed[-1]
+
+
 def start(paths: OrgPaths, **driver: Any) -> None:
     _drive_service(paths, "start", **driver)