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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentic-runner
-Version: 3.12.2
+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.2 → 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.2"
+__version__ = "3.13.0"
 
 __all__ = ["__version__"]

{agentic_runner-3.12.2 → 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,
@@ -250,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)
@@ -288,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))

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.