Files
skills/orchestrator/client/runner.py
T
Kevin Veen-BirkenbachandClaude Opus 5.5 78f2fec339 feat(match): merge and commit-tree previews, Match motion and Home tile
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>
2026-11-18 20:05:57 +00:00

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())