agentic-runner 3.12.1__tar.gz → 3.13.0__tar.gz

{agentic_runner-3.12.1 → agentic_runner-3.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentic-runner
-Version: 3.12.1
+Version: 3.13.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

{agentic_runner-3.12.1 → agentic_runner-3.13.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.12.1"
+__version__ = "3.13.0"
 
 __all__ = ["__version__"]

{agentic_runner-3.12.1 → agentic_runner-3.13.0}/src/agentic_runner/cli.py

@@ -15,6 +15,9 @@ the Organisation's cap.
 Runner (PRD issue 47, ``workstation.py``): one login agent per Organisation, managed by
 the user who hosts it, with no ``sudo`` anywhere.
 
+``skill install | print`` hands the setup skill to the person's own Claude Code or Codex
+(``skill.py``, console-v2 issue 21).
+
 The remaining subcommands are what a Directive calls back with, over its own attempt
 socket (``callback.py``): ``annotate``, ``artifact upload``, ``verb`` and ``message send |
 list`` (the Channel seam, PRD issue 52) and ``ask`` (a Question, issue 60). They read the
@@ -35,7 +38,7 @@ from collections.abc import Sequence
 from pathlib import Path
 
 from agentic_runner import __version__ as runner_version
-from agentic_runner import service, workstation
+from agentic_runner import service, skill, workstation
 from agentic_runner.callback import (
     CALLBACK_SOCKET_ENV,
     CALLBACK_TOKEN_ENV,
@@ -158,6 +161,12 @@ def main(argv: Sequence[str] | None = None) -> int:
         action="store_true",
         help="no TLS to Temporal -- a local development server only",
     )
+    install.add_argument(
+        "--acp-cli-kinds",
+        default=None,
+        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("--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"):
@@ -244,6 +253,18 @@ def main(argv: Sequence[str] | None = None) -> int:
         "--base", default="", help="`branch` only: the base branch; default the repository's"
     )
 
+    skill_parser = subcommands.add_parser(
+        "skill", help="the setup skill for your own Claude Code or Codex (console-v2 issue 21)"
+    )
+    skill_parser.add_argument("action", choices=("install", "print"))
+    only = skill_parser.add_mutually_exclusive_group()
+    only.add_argument(
+        "--claude", dest="targets", action="store_const", const=("claude",), help="Claude only"
+    )
+    only.add_argument(
+        "--codex", dest="targets", action="store_const", const=("codex",), help="Codex only"
+    )
+
     subcommands.add_parser("config", help="print the resolved configuration (flag > env > file)")
 
     arguments = parser.parse_args(argv)
@@ -282,6 +303,13 @@ def main(argv: Sequence[str] | None = None) -> int:
         for line in lines:
             print(line)
         return 0
+    if arguments.command == "skill":
+        if arguments.action == "print":
+            sys.stdout.write(skill.text())
+            return 0
+        for path in skill.install(arguments.targets or skill.TARGETS):
+            print(f"installed {path}")
+        return 0
     if arguments.command == "config":
         config = load_config(config_file=arguments.config, hooks_path=arguments.hooks_path)
         print(config.model_dump_json(indent=2))
@@ -342,6 +370,11 @@ def _install(arguments: argparse.Namespace, paths: workstation.OrgPaths) -> int:
     if not arguments.control_plane:
         print(f"--control-plane (or {CONTROL_PLANE_ENV}) is required", file=sys.stderr)
         return 2
+    try:
+        acp_cli_kinds = _acp_cli_kinds(arguments.acp_cli_kinds, paths)
+    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 = os.environ.get(AGENT_TOKEN_ENV, "").strip() or getpass.getpass(
         "Agent Token (yours from /me/runners, or the Organisation Admin's for an "
@@ -354,6 +387,7 @@ def _install(arguments: argparse.Namespace, paths: workstation.OrgPaths) -> int:
         temporal_tls=not arguments.temporal_plaintext,
         path=os.environ.get("PATH", ""),
         install_channel=workstation.install_channel(),
+        acp_cli_kinds=acp_cli_kinds,
     )
     try:
         lines = asyncio.run(
@@ -369,6 +403,15 @@ def _install(arguments: argparse.Namespace, paths: workstation.OrgPaths) -> int:
     return 0
 
 
+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:
+        return workstation.parse_acp_cli_kinds(flag)
+    if not paths.settings_file.is_file():
+        return ""
+    return workstation.WorkstationSettings.load(paths).acp_cli_kinds
+
+
 def _callback(arguments: argparse.Namespace) -> int:
     socket_path = os.environ.get(CALLBACK_SOCKET_ENV, "")
     token = os.environ.get(CALLBACK_TOKEN_ENV, "")

agentic_runner-3.13.0/src/agentic_runner/skill.py

@@ -0,0 +1,58 @@
+"""``agentic-runner skill install | print``: the setup skill for the person's own coding CLI.
+
+The skill (console-v2 issue 21) is read and run by the person's own Claude Code or Codex,
+so the control plane calls no LLM to onboard anyone (ADR-0010 §4). It ships inside the
+wheel so ``uvx agentic-runner skill install`` needs nothing but PyPI, and the copy a CLI
+reads is always the one that matches the Runner it installs.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from importlib.resources import files
+from pathlib import Path
+from typing import Literal
+
+SKILL_NAME = "agentic-runner-setup"
+
+Target = Literal["claude", "codex"]
+TARGETS: tuple[Target, ...] = ("claude", "codex")
+
+
+def text() -> str:
+    return files("agentic_runner").joinpath("skills", SKILL_NAME, "SKILL.md").read_text("utf-8")
+
+
+def skill_dir(target: Target, *, home: Path, environ: Mapping[str, str]) -> Path:
+    """Where each CLI reads a user skill from.
+
+    Claude Code honours ``CLAUDE_CONFIG_DIR`` for its whole user directory; Codex reads user
+    skills from ``~/.agents/skills``, not from ``CODEX_HOME``.
+    """
+
+    if target == "claude":
+        root = Path(environ.get("CLAUDE_CONFIG_DIR") or home / ".claude")
+    else:
+        root = home / ".agents"
+    return root / "skills" / SKILL_NAME
+
+
+def install(
+    targets: tuple[Target, ...],
+    *,
+    home: Path | None = None,
+    environ: Mapping[str, str] | None = None,
+) -> list[Path]:
+    written = []
+    for target in targets:
+        directory = skill_dir(
+            target,
+            home=home or Path.home(),
+            environ=os.environ if environ is None else environ,
+        )
+        directory.mkdir(parents=True, exist_ok=True)
+        path = directory / "SKILL.md"
+        path.write_text(text(), encoding="utf-8")
+        written.append(path)
+    return written

agentic_runner-3.13.0/src/agentic_runner/skills/agentic-runner-setup/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: agentic-runner-setup
+description: Install and register an Agentic OS Runner on this machine, a Docker host or a Kubernetes cluster, put the Contract's LLM credential in place, and confirm the Runner is online. Use when the person asks to set up, install or connect a Runner, or pastes the prompt from the console's welcome page.
+license: AGPL-3.0-only
+---
+
+# Set up an Agentic OS Runner
+
+You help a person who has never run a Runner. A **Runner** is the program that does their
+Agents' work: it runs Codex or Claude Code on a machine they choose and connects out to the
+Agentic OS control plane. It belongs to one **Organisation** (the company the work is for).
+
+The install documents in the `qtsone/agentic-runner` repository are the source for every
+command. Do not reconstruct a command from memory: open the section named in each step and
+follow it.
+
+## What the person gives you
+
+The prompt they pasted from the console holds these. Ask for any that is missing.
+
+- **Organisation**: a short local name for it, lowercase letters, digits and `-` (`acme`).
+- **Control plane URL**: the Runner's `controlPlane.url`, copied from the console's
+  Runners page. It is the only control plane address you use, and only as a value you
+  pass to the Runner. Never call it or any other control plane address yourself.
+- **Temporal address**: `host:port`, from the same page.
+
+The **Agent Token** is not one of them. It is the reusable credential a Runner registers
+with, and the person types it only where the Runner reads it, never into this
+conversation.
+
+## Rules
+
+- **Say before you run.** Before each command, show the person the exact command and what
+  it does, in one line.
+- **Stop on the first failure.** Show the exact error, link the doc section below that
+  covers it, and stop. Do not retry with other flags, do not work around it.
+- **Never ask for the Agent Token or any credential value in this conversation.** Anything
+  said here reaches the model vendor and stays in this CLI's history. Every command that
+  reads a credential is one the person runs in their own terminal, and the person types the
+  value there. If the person pastes a token or a key here anyway, do not use it: tell them
+  to revoke it in the console and mint or create a new one.
+- You use only the `agentic-runner` command, the standard tools named in the docs (`uv`,
+  `docker`, `kubectl`, `helm`) and read-only checks such as `command -v`.
+
+## Steps
+
+### 1. Look at the machine
+
+Run and report, in one short list:
+
+```sh
+uname -sm
+command -v uv python3 docker kubectl helm codex claude
+```
+
+A Runner does its work with **Codex** or **Claude Code** (each is an Agent Runtime). If the
+way the person picks runs on this machine and neither `codex` nor `claude` is found, say
+so and link their install pages
+(https://developers.openai.com/codex/cli, https://code.claude.com/docs/en/setup). You do
+not install them.
+
+### 2. Ask which way
+
+Ask the person to pick one, and open the matching document:
+
+| Way | When | Document |
+| --- | --- | --- |
+| This machine | A laptop or desktop they use every day. Needs `uv`. | https://github.com/qtsone/agentic-runner/blob/main/docs/workstation.md |
+| Docker | A server or always-on machine with Docker. | https://github.com/qtsone/agentic-runner/blob/main/docs/docker.md |
+| Kubernetes | A cluster they run, with `kubectl` and `helm`. | https://github.com/qtsone/agentic-runner/blob/main/docs/helm.md |
+
+Read its "Before you start" section with the person, and stop if something on it is
+missing.
+
+### 3. Install and register
+
+**This machine.** Follow
+https://github.com/qtsone/agentic-runner/blob/main/docs/workstation.md#install. Install the
+Runner, then show the person the command that registers it for the Organisation and ask
+them to run it in their own terminal. The Runner asks them for the Agent Token there,
+without showing it:
+
+```sh
+uv tool install agentic-runner
+agentic-runner install <org> --control-plane <control-plane-url> --temporal-address <temporal-address>
+```
+
+You run the first line. Do not run the second yourself: wait until the person says it
+finished, and ask for its last lines of output.
+
+**Docker.** Follow
+https://github.com/qtsone/agentic-runner/blob/main/docs/docker.md#the-env-file and then
+https://github.com/qtsone/agentic-runner/blob/main/docs/docker.md#docker-run. Create
+`runner.env` with the URL and the address filled in, and ask the person to add the Agent
+Token line to it themselves.
+
+**Kubernetes.** Follow
+https://github.com/qtsone/agentic-runner/blob/main/docs/helm.md#install. The person creates
+the token Secret themselves (the `read -rs` lines in that section). You run the `helm`
+command.
+
+`registration refused (…)` means the token is revoked or expired, the Account is on hold,
+or the Organisation has reached its Runner limit: the person mints a new token in the
+console. Other errors: the "Check it" section of the same document.
+
+### 4. Put the Contract's LLM credential in place
+
+A **Contract** is the agreement under which the person works for the Organisation. It says
+whose LLM key or subscription the Agents spend. Ask which of the two the Contract uses.
+
+- **An API key (a Credential Reference).** A Credential Reference is the name of a secret
+  whose value lives only on the Runner. On this machine, ask the person to run, in their own
+  terminal, the line from
+  https://github.com/qtsone/agentic-runner/blob/main/docs/workstation.md#operate:
+
+  ```sh
+  printf %s "$VALUE" | agentic-runner credential set <org> <reference>
+  ```
+
+  For Docker and Kubernetes the value is delivered from the console, sealed to the Runner:
+  https://github.com/qtsone/agentic-runner/blob/main/docs/helm.md#the-recipient-key.
+- **A Codex or Claude Code subscription.** This works only on a Runner the person hosts
+  themselves. Send them to the Contract's page in the console and its **Connect** button:
+  the console opens the vendor's sign-in in their browser and the Runner finishes it. See
+  https://github.com/qtsone/agentic-runner/blob/main/docs/workstation.md#sign-in-to-codex-and-claude-code.
+  You have no sign-in of your own to run, and you do not run `codex login` or
+  `claude auth login`.
+
+### 5. Wait for the Runner to come online
+
+On this machine, run every 10 seconds, for at most 3 minutes:
+
+```sh
+agentic-runner status <org>
+```
+
+The Runner is online when `process` says `running` and `heartbeat` shows a number of
+seconds, not `never`. For Docker and Kubernetes, use the commands in the document's "Check
+it" section. If 3 minutes pass, stop and show the last output and the "Check it" link.
+
+### 6. Report
+
+One screen, nothing more:
+
+- the way, the Organisation and the Runner's identity line from `status`;
+- whether the LLM credential is in place, or the one thing the person still does in the
+  console;
+- the `next` line `status` prints: where in the console to see the Runner and give it work.

{agentic_runner-3.12.1 → agentic_runner-3.13.0}/src/agentic_runner/workstation.py

@@ -50,6 +50,7 @@ from agentic_runner.host_store import open_workstation_store
 from agentic_runner.lifecycle import LifecycleOutbox
 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.runner_registration import (
     CliVersion,
     EgressPosture,
@@ -75,6 +76,7 @@ __all__ = [
     "install",
     "install_channel",
     "locate_clis",
+    "parse_acp_cli_kinds",
     "require_any_cli",
     "run_environment",
     "run_process",
@@ -204,6 +206,9 @@ class WorkstationSettings(BaseModel):
     # would not find a Homebrew or `~/.local/bin` CLI without it.
     path: str
     install_channel: InstallChannel
+    # The Runner's `ACP_CLI_KINDS`, kept here rather than hand-added to the login agent,
+    # which every `install` rewrites (QTS-1355).
+    acp_cli_kinds: str = ""
 
     def save(self, paths: OrgPaths) -> None:
         paths.settings_file.write_text(self.model_dump_json(indent=2), encoding="utf-8")
@@ -218,6 +223,23 @@ class WorkstationSettings(BaseModel):
         return cls.model_validate_json(paths.settings_file.read_text(encoding="utf-8"))
 
 
+def parse_acp_cli_kinds(value: str) -> str:
+    """``--acp-cli-kinds``, refused if it names a kind with no pinned bridge.
+
+    The Runner itself drops such a kind without a word, so a typo here would turn ACP off
+    as quietly as the rewritten login agent did (QTS-1355).
+    """
+
+    kinds = [kind.strip() for kind in value.split(",") if kind.strip()]
+    unknown = sorted(set(kinds) - ACP_BRIDGES.keys())
+    if unknown:
+        raise ValueError(
+            f"--acp-cli-kinds names {', '.join(unknown)}; a pinned ACP bridge exists only for "
+            f"{', '.join(sorted(ACP_BRIDGES))}"
+        )
+    return ",".join(dict.fromkeys(kinds))
+
+
 def install_channel(
     platform: str = sys.platform, *, executable: str = sys.executable
 ) -> InstallChannel:
@@ -235,7 +257,7 @@ def run_environment(paths: OrgPaths, settings: WorkstationSettings) -> dict[str,
     a unit, a task -- stays a one-liner, and the three OSes cannot drift apart.
     """
 
-    return {
+    environment = {
         "PATH": settings.path,
         "AGENTIC_RUNNER_STATE_DIR": str(paths.state_dir),
         "AGENTIC_RUNNER_WORKSPACE_ROOT": str(paths.workspaces),
@@ -254,6 +276,11 @@ def run_environment(paths: OrgPaths, settings: WorkstationSettings) -> dict[str,
         # port inherited from a pod-style environment would collide on the second one.
         service.READINESS_PORT_ENV: "0",
     }
+    # Only when set: a login agent hand-edited with `ACP_CLI_KINDS` before QTS-1355 keeps
+    # ACP on across an upgrade until its next `install`.
+    if settings.acp_cli_kinds:
+        environment["ACP_CLI_KINDS"] = settings.acp_cli_kinds
+    return environment
 
 
 # ------------------------------------------------------------------ the CLIs