#!/usr/bin/env python3 """Args: --port: port of the Agent Orchestrator on 127.0.0.1; the signature's origin is http://localhost:. --interval: seconds between two polls of the hub. --approvers: the pinned passkeys, e.g. ~/.config/kvb-orchestrator/approvers.json. --replay: the runner's replay store, outside the hub's reach, e.g. ~/.local/state/kvb-orchestrator-approvals/runner.json. --rasci: the installed register script, e.g. ~/.claude/skills/kvb-org-rasci/scripts/rasci.py; optional. --council: the council directory holding rasci.json, the agents' AGENTS_COUNCIL_ROOT; optional, task changes need both. --gates: the installed gates script, e.g. ~/.claude/skills/kvb-check-gate/scripts/gates.py; optional, gate changes need it. --once: handle the queued jobs once and exit. Returns: Runs as the operator, outside any sandbox, every operator command a pinned passkey signed in the Agent Orchestrator: exactly the signed text, with bash in the signed directory, each signature once and before its expiry. Runs every signed task change (priority pin, status, dependency or WSJF estimate; a board batch is one job per change) as `python3 -I -B ` from / without a shell, after checking the argv shape itself, and kills its process group after 30 s; rasci.py refuses a cycle or a done with an open key result, and its reason is the job's output. Runs every signed gate change (rule set|drop, parents add|drop) the same way as `python3 -I -B ` with the operator's HOME, so gates.py writes its default gates.db. Refuses task changes without --rasci and --council or into a council that is a symlink or another uid's, gate changes without --gates, and every other job. Posts the last 200 output lines back while it runs and the exit code at its end. Before every poll it posts, for each open operator row that is a git merge of a full commit id (staged_diff.merge_of) whose HEAD differs from the preview the hub holds, staged_diff.merge_preview, which its Match card shows; such a merge whose job names the previewed HEAD is refused once HEAD moved. The exit code is 0. """ from __future__ import annotations import argparse import collections import contextlib import json import os import signal import stat import subprocess import sys import threading import time import urllib.error import urllib.request from collections.abc import Callable from pathlib import Path from typing import NamedTuple import hub_api import hub_limits import signing import staged_diff import verifier LINES = 200 PREVIEWS = "/api/runner/previews" ERROR_LIMIT = 500 PREVIEW_FAILURES = (OSError, ValueError, staged_diff.DiffError) BEAT = 2.0 SAFE_PATH = "/usr/bin:/bin" TASK_JOB = "task" TASK_LIMIT = 30.0 GATE_JOB = "gate" REFUSED = "refused: no valid operator signature for this command" UNREGISTERED = "refused: this runner was started without --rasci and --council; reinstall its unit with make orchestrator-runner" UNGATED = "refused: this runner was started without --gates; reinstall its unit with make orchestrator-runner" class Register(NamedTuple): rasci: Path council: Path def call(base: str, path: str, payload: dict | None) -> dict: headers = dict(hub_api.GUARD) data = None if payload is not None: headers["Content-Type"] = "application/json" data = json.dumps(payload).encode() request = urllib.request.Request(f"{base}{path}", data=data, headers=headers, method="GET" if payload is None else "POST") return hub_api.call(request, hub_api.SLACK) def collect(stream: object, tail: collections.deque, lock: threading.Lock) -> None: # The reader closes the pipe at EOF: a close in execute() would block on the buffer lock this read holds and SIGPIPE a command still running. with stream: for line in stream: with lock: tail.append(line) def refusal(job: dict, trust: verifier.Trust, now: float) -> str | None: """Args: job: the claimed job with task, command, directory and proof. trust: the pinned keys, the runner's replay store and the origin. now: the current time in epoch seconds. Returns: Why the job must not run, or None when a pinned key signed it. """ try: verifier.check(job.get("proof"), signing.operator_item(job["task"], job["command"], job["directory"]), "", trust, now) except (signing.Refused, OSError) as error: return f"{REFUSED}: {error}" return None def task_refusal(job: dict, trust: verifier.Trust, now: float) -> str | None: """Args: job: the claimed task change with task, argv and proof. trust: the pinned keys, the runner's replay store and the origin. now: the current time in epoch seconds. Returns: Why the change must not run, or None when its argv has one of the shapes signing.task_argv() allows and a pinned key signed it. """ try: argv = signing.task_argv(job["task"], job["argv"]) verifier.check(job.get("proof"), signing.task_item(job["task"], argv), "", trust, now) except (signing.Refused, OSError) as error: return f"{REFUSED}: {error}" return None def gate_refusal(job: dict, trust: verifier.Trust, now: float) -> str | None: """Args: job: the claimed gate change with argv and proof. trust: the pinned keys, the runner's replay store and the origin. now: the current time in epoch seconds. Returns: Why the change must not run, or None when signing.gate_argv() accepts its argv and a pinned key signed it. """ try: argv = signing.gate_argv(job["argv"]) verifier.check(job.get("proof"), signing.gate_item(argv), "", trust, now) except (signing.Refused, OSError) as error: return f"{REFUSED}: {error}" return None def moved(job: dict) -> str | None: """Args: job: a claimed operator command; head, when set, is the HEAD its Match card previewed the merge against. Returns: Why a git merge (staged_diff.merge_of) must not run because HEAD is no longer that commit or cannot be read; None otherwise. """ found = staged_diff.merge_of(job["command"], job["directory"]) if job.get("head") else None if found is None: return None try: head = staged_diff.head_of(found[0]) except PREVIEW_FAILURES as error: return f"refused: HEAD cannot be read, so the merge is not the one previewed: {error}" return None if head == job["head"] else f"refused: HEAD moved from {job['head'][:12]} to {head[:12]} since the Match card previewed the merge" def preview(row: dict, rules: Path | None) -> dict | None: """Args: row: an open operator row with task, command, directory and head, the HEAD of the preview the hub holds, None for none. rules: the MEDUSA rules directory. Returns: The preview to post for a git merge row whose HEAD differs from the hub's: staged_diff.merge_preview, or {head, error} when it cannot be built; None for every other row. """ found = staged_diff.merge_of(row["command"], row["directory"]) if found is None: return None try: head = staged_diff.head_of(found[0]) except PREVIEW_FAILURES as error: head, shown = "", {"error": str(error)[:ERROR_LIMIT]} else: shown = None if head == row["head"]: return None if shown is None: try: shown = staged_diff.merge_preview(found[0], found[1], rules) except PREVIEW_FAILURES as error: shown = {"error": str(error)[:ERROR_LIMIT]} return {"task": row["task"], "command": row["command"], "head": head, **shown} def previews(base: str, rules: Path | None) -> None: for row in call(base, PREVIEWS, None)["rows"]: shown = preview(row, rules) if shown is not None and len(json.dumps(shown).encode()) > hub_limits.DIFF_BODY_LIMIT: shown = {"task": row["task"], "command": row["command"], "head": shown["head"], "error": f"the preview passes the hub's {hub_limits.DIFF_BODY_LIMIT} bytes"} if shown is not None: call(base, PREVIEWS, shown) def council_refusal(council: Path) -> str | None: """Args: council: the directory rasci.py writes the register into. Returns: Why no task change may run there, or None for a real directory of the runner's own uid, given by an absolute path. """ if not council.is_absolute(): return f"refused: the council {council} is no absolute path" try: found = os.lstat(council) except OSError as error: return f"refused: the council {council} cannot be read: {error}" if not stat.S_ISDIR(found.st_mode) or found.st_uid != os.geteuid(): return f"refused: the council {council} is a symlink, no directory or not owned by uid {os.geteuid()}" return None def execute(job: dict, report: Callable[[dict], None]) -> int: """Args: job: the claimed and verified job with command and directory. report: called with {"output", "code", "refused"}; code None while the command runs. Returns: The exit code. """ return spawn(["bash", "-c", job["command"]], job["directory"], None, report) def change(job: dict, register: Register, report: Callable[[dict], None]) -> int: """Args: job: the claimed and verified task change with task and argv. register: the register script and the council it writes. report: called with {"output", "code", "refused"}. Returns: The exit code of rasci.py, run from / on the argv task_argv() checked. Raises: signing.Refused for an argv of any other shape. """ argv = signing.task_argv(job["task"], job["argv"]) env = {"PATH": SAFE_PATH, "HOME": str(Path.home()), "AGENTS_COUNCIL_ROOT": str(register.council)} return spawn([sys.executable, "-I", "-B", str(register.rasci), *argv], "/", env, report, TASK_LIMIT) def gate(job: dict, gates: Path, report: Callable[[dict], None]) -> int: """Args: job: the claimed and verified gate change with argv. gates: the gates script. report: called with {"output", "code", "refused"}. Returns: The exit code of gates.py, run from / on the argv gate_argv() checked. Raises: signing.Refused for an argv of any other shape. """ argv = signing.gate_argv(job["argv"]) env = {"PATH": SAFE_PATH, "HOME": str(Path.home())} return spawn([sys.executable, "-I", "-B", str(gates), *argv], "/", env, report, TASK_LIMIT) def spawn(argv: list[str], cwd: str, env: dict[str, str] | None, report: Callable[[dict], None], limit: float | None = None) -> int: """Args: argv: the program and its arguments, run without a shell. cwd: the directory it runs in. env: its whole environment, or None for the runner's own. report: called with {"output", "code", "refused"}; code None while the program runs. limit: seconds until its whole process group is killed, or None to let it run. Returns: The exit code, -9 after the kill. """ tail: collections.deque = collections.deque(maxlen=LINES) lock = threading.Lock() try: process = subprocess.Popen( argv, cwd=cwd, env=env, stdin=subprocess.DEVNULL, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True, errors="replace", start_new_session=True, ) except OSError as error: report({"output": f"could not start: {error}", "code": 127, "refused": False}) return 127 reader = threading.Thread(target=collect, args=(process.stdout, tail, lock), daemon=True) reader.start() deadline = None if limit is None else time.monotonic() + limit while True: try: code = process.wait(BEAT if deadline is None else max(0.0, min(BEAT, deadline - time.monotonic()))) break except subprocess.TimeoutExpired: if deadline is not None and time.monotonic() >= deadline: with contextlib.suppress(ProcessLookupError): os.killpg(process.pid, signal.SIGKILL) code = process.wait() with lock: tail.append(f"killed after {limit:g} s\n") break with lock: output = "".join(tail) report({"output": output, "code": None, "refused": False}) reader.join() report({"output": "".join(tail), "code": code, "refused": False}) return code def sender(base: str, job_id: str) -> Callable[[dict], None]: def send(result: dict) -> None: try: call(base, f"/api/runner/{job_id}/report", result) except (OSError, ValueError, TypeError): return return send def cycle(base: str, trust: verifier.Trust, register: Register | None, gates: Path | None = None) -> None: for job in call(base, "/api/runner/jobs", None)["jobs"]: try: claimed = call(base, f"/api/runner/{job['id']}/claim", {}) except urllib.error.HTTPError: continue send = sender(base, claimed["id"]) kind = claimed.get("kind") if kind == TASK_JOB: reason = UNREGISTERED if register is None else council_refusal(register.council) or task_refusal(claimed, trust, time.time()) elif kind == GATE_JOB: reason = UNGATED if gates is None else gate_refusal(claimed, trust, time.time()) else: reason = refusal(claimed, trust, time.time()) or moved(claimed) if reason is not None: send({"output": reason, "code": None, "refused": True}) elif kind == TASK_JOB: change(claimed, register, send) elif kind == GATE_JOB: gate(claimed, gates, send) else: execute(claimed, send) def main() -> int: parser = argparse.ArgumentParser(prog="runner") parser.add_argument("--port", type=int, required=True) parser.add_argument("--interval", type=float, required=True) parser.add_argument("--approvers", type=Path, required=True) parser.add_argument("--replay", type=Path, required=True) parser.add_argument("--rasci", type=Path) parser.add_argument("--council", type=Path) parser.add_argument("--gates", type=Path) parser.add_argument("--once", action="store_true") args = parser.parse_args() base = hub_api.base_url(args.port) trust = verifier.Trust(approvers=args.approvers, replay=args.replay, origin=signing.origin_of(args.port)) register = Register(rasci=args.rasci, council=args.council) if args.rasci and args.council else None rules, told = staged_diff.rules_root(), "" while True: try: previews(base, rules) told = "" except (OSError, ValueError, KeyError, TypeError) as error: if str(error) != told: print(f"runner: no merge previews: {error}", file=sys.stderr) told = str(error) try: cycle(base, trust, register, args.gates) except (OSError, ValueError, KeyError, TypeError): pass if args.once: return 0 time.sleep(args.interval) if __name__ == "__main__": raise SystemExit(main())