The host runner computes a merge preview for each operator row that merges or commits and posts it to the runner-only /api/runner/previews, and an ask of git commit ships the staged commit tree; Match cards show what the merge brings in onto HEAD, or why no preview exists. Cards fly off with their verdict stamp unless reduced motion is set, Match gets its own button in Tasks and a Home tile that keeps the live stack, and the 3D graph and the faces fix land with it. 🎯 Fix: 85 % 💥 Break: 10 % 💸 Tokens: – ⏱️ Velocity: – 🛡️ Security: 100 % 🏆 Score: 77 🚦 Gate: ⛔ fix 85 % < 90, break 10 % > 5 Created-with: https://s.veen.world/skills Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
399 lines
15 KiB
Python
Executable File
399 lines
15 KiB
Python
Executable File
#!/usr/bin/env python3
|
|
"""Args:
|
|
--port: port of the Agent Orchestrator on 127.0.0.1; the signature's origin is
|
|
http://localhost:<port>.
|
|
--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 <rasci> <argv>` 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 <gates> <argv>` 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())
|