raidlock 0.1.0__py3-none-any.whl

raidlock/__init__.py

@@ -0,0 +1,11 @@
+"""raidlock: a local-first lease-and-review board for coding agents from any provider."""
+
+import sys
+
+__version__ = "0.1.0"
+MINIMUM_PYTHON = (3, 11)
+
+if sys.version_info < MINIMUM_PYTHON:
+    from ._python import refuse
+
+    refuse(MINIMUM_PYTHON)

raidlock/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

raidlock/_python.py

@@ -0,0 +1,58 @@
+"""Refuse to run on a Python older than raidlock supports, with one clear line.
+
+This module must stay importable by old interpreters: plain syntax and the standard library only. A hook guard that
+runs inside a raidlock workspace denies the tool call instead of failing open."""
+
+import json
+import os
+import sys
+
+GUARDS = ("pre-write", "pre-read", "pre-bash", "pre-urgent")
+
+
+def message(minimum):
+    have = ".".join(str(n) for n in sys.version_info[:3])
+    need = ".".join(str(n) for n in minimum)
+    return (
+        "raidlock needs Python {need} or newer, but {exe} is Python {have}. Install raidlock with "
+        "`uv tool install raidlock` or `pipx install raidlock`, or set RAIDLOCK_PYTHON to a Python {need}+ "
+        "interpreter."
+    ).format(need=need, exe=sys.executable or "python", have=have)
+
+
+def board_above(start):
+    cur = os.path.abspath(start or os.getcwd())
+    while True:
+        if os.path.isfile(os.path.join(cur, ".board", "board.json")):
+            return True
+        parent = os.path.dirname(cur)
+        if parent == cur:
+            return False
+        cur = parent
+
+
+def hook_input():
+    try:
+        data = json.loads(sys.stdin.read() or "{}")
+    except (OSError, ValueError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def refuse(minimum):
+    text = message(minimum)
+    if any(arg in GUARDS for arg in sys.argv[1:]) and not sys.stdin.isatty():
+        data = hook_input()
+        if board_above(data.get("cwd")):
+            out = {
+                "hookSpecificOutput": {
+                    "hookEventName": "PreToolUse",
+                    "permissionDecision": "deny",
+                    "permissionDecisionReason": "raidlock: " + text,
+                }
+            }
+            sys.stdout.write(json.dumps(out, separators=(",", ":")))
+            sys.stdout.flush()
+            raise SystemExit(0)
+    sys.stderr.write(text + "\n")
+    raise SystemExit(1)

raidlock/achievements.py

@@ -0,0 +1,156 @@
+"""Achievements earned from recorded board events. The web UI shows them unless the viewer turns them off.
+
+Every rule reads the transcript and cards; nothing is stored and nothing is granted. Names and art are original to
+raidlock.
+"""
+
+import datetime
+
+from .core import clock, receipts
+from .web.replay import data_of, history, records, text_of
+
+CLEAN_CARDS = 50
+SWIFT_MINUTES = 30
+PEACE_DAYS = 7
+TITLES = {
+    "clean-hands": "the Unbroken",
+    "first-seal": "the Sealbearer",
+    "second-opinion": "the Wise",
+    "clean-run": "the Flawless",
+    "swift-blade": "the Swift",
+    "night-watch": "of the Night Watch",
+    "peacekeeper": "the Peacekeeper",
+}
+CATALOG = (
+    ("first-light", "First Light", "A card reaches done for the first time.", "sun"),
+    ("first-seal", "Wax Seal", "The first verify receipt that passes and checks out.", "seal"),
+    ("second-opinion", "Second Opinion", "A review from a different provider than the card's owner.", "eyes"),
+    ("second-draft", "Second Draft", "A card that got changes requested and was then approved.", "quill"),
+    ("many-voices", "Many Voices", "Cards finished by agents from two or more providers.", "chord"),
+    (
+        "clean-hands",
+        "Clean Hands",
+        f"One agent finishes {CLEAN_CARDS} cards with zero recorded lock violations.",
+        "hands",
+    ),
+    ("clean-run", "Clean Run", "A card closes on its first verify run.", "rune"),
+    ("peacekeeper", "Peacekeeper", f"{PEACE_DAYS} days of finished cards with no lock violation.", "shield"),
+    ("swift-blade", "Swift Blade", f"A card goes from claim to done within {SWIFT_MINUTES} minutes.", "blade"),
+    ("night-watch", "Night Watch", "A card is finished between midnight and 4 a.m. local time.", "moon"),
+)
+
+
+def evaluate(board):
+    agents = board.agents()
+    cards = {c["id"]: c for c in board.cards()}
+
+    def provider(name):
+        return (agents.get(name) or {}).get("provider", "") or ""
+
+    owners = {}
+    earned = {}
+    violations = {}
+    done_by = {}
+    changed = set()
+    providers_done = {}
+    first_verify = {}
+    claimed_at = {}
+    since_peace = None
+
+    def win(key, r, by, detail):
+        if key not in earned:
+            earned[key] = {"at": r.get("ts", ""), "seq": r.get("seq", 0), "by": by, "detail": detail}
+
+    for r in records(board):
+        kind, task = r.get("kind"), r.get("taskId", "") or ""
+        sender = (r.get("from") or {}).get("agent", "")
+        data = data_of(r)
+        when = clock.parse(r.get("ts", ""))
+        if since_peace is None and when:
+            since_peace = when
+        if kind == "status" and data.get("a2a_state") == "working" and "fence" in data:
+            owners[task] = sender
+            if when:
+                claimed_at[task] = when
+        if data.get("event") == "lock_violation":
+            who = data.get("agent") or sender
+            violations[who] = violations.get(who, 0) + 1
+            since_peace = when or since_peace
+        owner = owners.get(task) or cards.get(task, {}).get("owner", "")
+        if kind == "status" and data.get("lane") == "done" and task:
+            win("first-light", r, owner, task)
+            if first_verify.get(task) is True:
+                win("clean-run", r, owner, task)
+            start = claimed_at.get(task)
+            if when and start and when - start <= datetime.timedelta(minutes=SWIFT_MINUTES):
+                win("swift-blade", r, owner, task)
+            if when and when.astimezone().hour < 4:
+                win("night-watch", r, owner, task)
+            if when and since_peace and when - since_peace >= datetime.timedelta(days=PEACE_DAYS):
+                win("peacekeeper", r, owner, f"{PEACE_DAYS} days without a lock violation")
+            if owner:
+                done_by[owner] = done_by.get(owner, 0) + 1
+                if done_by[owner] >= CLEAN_CARDS and not violations.get(owner):
+                    win("clean-hands", r, owner, f"{done_by[owner]} cards")
+                if provider(owner):
+                    providers_done.setdefault(provider(owner), owner)
+                    if len(providers_done) >= 2:
+                        win("many-voices", r, owner, ", ".join(sorted(providers_done)))
+        if kind == "verify" and task and task not in first_verify:
+            first_verify[task] = bool(data.get("passed"))
+        if kind == "verify" and data.get("passed") and task in cards and receipts.valid(board, cards[task], data):
+            win("first-seal", r, owner, task)
+        if kind == "review" and data.get("verdict") in ("approve", "changes") and task:
+            if owner and provider(sender) and provider(owner) and provider(sender) != provider(owner):
+                win("second-opinion", r, sender, f"{provider(sender)} reviewed {provider(owner)} on {task}")
+            if data["verdict"] == "changes":
+                changed.add(task)
+            elif task in changed:
+                win("second-draft", r, owner, task)
+        if kind == "status" and text_of(r).endswith("reopened"):
+            changed.discard(task)
+    clean = [n for n, d in done_by.items() if not violations.get(n)]
+    best = max([done_by[n] for n in clean] + [0])
+    out = []
+    for key, name, desc, art in CATALOG:
+        row = {"id": key, "name": name, "description": desc, "art": art, "earned": key in earned}
+        row.update(earned.get(key, {"at": "", "seq": 0, "by": "", "detail": ""}))
+        if key == "clean-hands":
+            row["progress"] = {"value": min(best, CLEAN_CARDS), "goal": CLEAN_CARDS}
+        elif key == "many-voices":
+            row["progress"] = {"value": min(len(providers_done), 2), "goal": 2}
+        out.append(row)
+    titles = {}
+    for key, title in TITLES.items():
+        who = earned.get(key, {}).get("by")
+        if who and who not in titles:
+            titles[who] = title
+    return {
+        "titles": titles,
+        "incomplete_history": history(board)[2],
+        "last": history(board)[1],
+        "achievements": out,
+        "earned": sum(1 for a in out if a["earned"]),
+        "total": len(out),
+    }
+
+
+def payload(board, query):
+    return evaluate(board)
+
+
+def _handle(ctx, args):
+    result = evaluate(ctx.board)
+    lines = [f"{result['earned']}/{result['total']} earned"]
+    for a in result["achievements"]:
+        mark = "x" if a["earned"] else " "
+        extra = f" by {a['by']} ({a['detail']})" if a["earned"] and a["by"] else ""
+        prog = a.get("progress")
+        if not a["earned"] and prog:
+            extra = f" ({prog['value']}/{prog['goal']})"
+        lines.append(f"[{mark}] {a['name']}: {a['description']}{extra}")
+    return result, "\n".join(lines)
+
+
+def register_cli(add_command):
+    add_command("achievements", "achievements earned from recorded board events", None, _handle)

raidlock/approvals.py

@@ -0,0 +1,237 @@
+"""Approval inbox: one list of everything waiting for a human, each item with copy-ready commands.
+
+Items are derived from board state on every read, so an item resolves itself when the state that raised it changes:
+a card that passes its done gate is ready to close, a done card whose runner patch still applies is a pending
+apply, a review card short of approvals or a receipt is a pending review, and blocked cards, undecided duels,
+stuck resurrections and pending lessons are lead decisions. Reading the inbox never changes the board."""
+
+import contextvars
+import os
+import re
+
+from . import duel
+from .core.errors import Precondition, RaidlockError
+from .core.hints import lead_cmd, lead_secret_src, quote_path, short_path
+from .runners import policy
+from .runners import workspace as W
+from .runners.runner import latest_patch
+
+KINDS = ("close", "apply", "review", "duel", "decision", "lore")
+APPLY_CHECKS = 10
+TEXT_CAP = 300
+
+
+_short = short_path
+_q = quote_path
+
+
+WEB_LEAD_SRC = '"$LEAD_SECRET_FILE"'
+_LEAD_SRC = contextvars.ContextVar("lead_secret_src", default=None)
+
+
+def web_lead_src(board):
+    """What the web board shows after --lead-secret: `keychain` or the real secret file path when it is under the
+    home folder (shown as ~/...), otherwise the LEAD_SECRET_FILE shell variable the getting-started guide sets up."""
+    src = lead_secret_src(board)
+    return src if src == "keychain" or src.startswith("~/") else WEB_LEAD_SRC
+
+
+def _lead(board, rest):
+    secret = _LEAD_SRC.get()
+    return f"raid --lead-secret {secret} {rest}" if secret else lead_cmd(board, rest, prog="raid")
+
+
+def _clip(text):
+    text = " ".join(str(text or "").split())
+    return text if len(text) <= TEXT_CAP else text[: TEXT_CAP - 3] + "..."
+
+
+def _item(kind, card, reason, commands, **extra):
+    cid = card["id"] if card else extra.pop("ref", "")
+    return {
+        "id": f"{kind}:{cid}",
+        "kind": kind,
+        "card": cid if card else "",
+        "title": _clip(card.get("title", "")) if card else _clip(extra.pop("title", "")),
+        "reason": _clip(reason),
+        "since": (card or {}).get("updated", "") or extra.pop("since", ""),
+        "commands": commands,
+        **extra,
+    }
+
+
+def _review_items(board, card):
+    cid = card["id"]
+    try:
+        board._done_gate(card)
+    except Precondition as e:
+        commands = []
+        if "verification" in e.message or "verify" in e.message:
+            if card.get("verify_cmd"):
+                commands.append(_lead(board, f"verify {_q(cid)}"))
+            else:
+                commands.append(_lead(board, f'edit {_q(cid)} --verify-cmd "<check>"'))
+        if "review" in e.message:
+            commands += [
+                _lead(board, f"delegate {_q(cid)} --to <runtime> --as reviewer"),
+                f"raid review {_q(cid)} --verdict approve   # as a reviewer agent",
+            ]
+        commands.append(f"raid show {_q(cid)}")
+        return [_item("review", card, e.message, commands)]
+    except RaidlockError as e:
+        return [_item("review", card, e.message, [f"raid show {_q(cid)}"])]
+    reason = "passes the done gate"
+    approved = board.approvals(card)
+    if approved:
+        reason += "; approved by " + ", ".join(approved)
+    return [_item("close", card, reason, [_lead(board, f"done {_q(cid)}")])]
+
+
+def _apply_item(board, card):
+    folder, _ = latest_patch(board, card["id"])
+    if not folder:
+        return None
+    patch = os.path.join(folder, "changes.patch")
+    try:
+        target = policy.target(board.workspace, board.dir, card["locks"])
+        W.git(target["path"], "apply", "--check", patch)
+    except (RaidlockError, OSError):
+        return None
+    repo = os.path.relpath(target["path"], board.workspace)
+    return _item(
+        "apply",
+        card,
+        f"done; its runner patch is not in {repo} yet",
+        [f"git -C {_q(repo)} apply --index {_q(patch)}", f"git -C {_q(repo)} diff --cached --stat"],
+        patch=_short(patch),
+    )
+
+
+def _blocked_item(board, card):
+    cid = card["id"]
+    last = next((n["text"] for n in reversed(card.get("notes", []))), "")
+    commands = [
+        f"raid show {_q(cid)}",
+        _lead(board, f"resume {_q(cid)}"),
+        _lead(board, f"resurrect {_q(cid)} --dry-run"),
+    ]
+    if card.get("owner"):
+        commands.append(f"raid claim {_q(cid)} --take-over   # as another worker")
+    last = last[len("-> blocked") :].strip(" ()") if last.startswith("-> blocked") else last
+    return _item("decision", card, f"blocked: {last}" if last else "blocked", commands)
+
+
+def _duel_item(board, card):
+    record = duel.load(board, card["id"])
+    if not record or record.get("status") != "decide":
+        return None
+    verified = [s for s in record.get("sides", []) if duel.passing(board, card["id"], s)]
+    commands = [_lead(board, f"duel {_q(card['id'])}")]
+    commands += [_lead(board, f"duel {_q(card['id'])} --winner {_q(s['label'])}") for s in verified]
+    reason = (
+        "duel finished; verified: " + ", ".join(f"{s['label']} ({s['runtime']})" for s in verified)
+        if verified
+        else "duel finished; no contestant has a passing signed receipt"
+    )
+    return _item("duel", card, reason, commands)
+
+
+def _lore_items(board):
+    try:
+        from .lore import Vault
+
+        rows = Vault.for_board(board).pending()
+    except (ImportError, RaidlockError, OSError):
+        return []
+    return [
+        _item(
+            "lore",
+            None,
+            "lesson waiting for approval",
+            [_lead(board, f"lore approve {_q(x['id'])}"), _lead(board, f"lore reject {_q(x['id'])}")],
+            ref=x["id"],
+            title=x.get("text", ""),
+            since=x.get("created", ""),
+        )
+        for x in rows
+        if isinstance(x.get("id"), str) and re.fullmatch(r"[a-f0-9]{12}", x["id"])
+    ]
+
+
+def collect(board, check_apply=True, secret=None):
+    """All pending items, most actionable first. Read-only. Lead commands carry the lead secret file's path, or
+    `secret` (the web board passes web_lead_src)."""
+    token = _LEAD_SRC.set(secret)
+    try:
+        return _collect(board, check_apply)
+    finally:
+        _LEAD_SRC.reset(token)
+
+
+def _collect(board, check_apply):
+    cards = board.cards()
+    items = []
+    duels = {}
+    for card in cards:
+        try:
+            found = _duel_item(board, card)
+        except RaidlockError:
+            found = None
+        if found:
+            duels[card["id"]] = found
+    for card in cards:
+        if card["lane"] == "review":
+            items += _review_items(board, card)
+        elif card["lane"] == "blocked" and card["id"] not in duels:
+            items.append(_blocked_item(board, card))
+    if check_apply:
+        done = sorted(
+            (c for c in cards if c["lane"] == "done" and not c.get("evidence")),
+            key=lambda c: c.get("updated", ""),
+            reverse=True,
+        )
+        for card in done[:APPLY_CHECKS]:
+            found = _apply_item(board, card)
+            if found:
+                items.append(found)
+    items += list(duels.values())
+    items += _lore_items(board)
+    order = {k: i for i, k in enumerate(KINDS)}
+    items.sort(key=lambda x: (order[x["kind"]], x["since"], x["id"]))
+    counts = {k: sum(1 for x in items if x["kind"] == k) for k in KINDS}
+    return {"workspace": board.name, "items": items, "counts": counts, "total": len(items)}
+
+
+def render(result):
+    if not result["items"]:
+        return "Nothing needs you right now."
+    urgent = sum(x["kind"] != "lore" for x in result["items"])
+    lines = [f"{urgent} item(s) need you in {result['workspace']}:"]
+    lore_heading = False
+    for x in result["items"]:
+        if x["kind"] == "lore" and not lore_heading:
+            lines.append("Lore inbox (low priority):")
+            lore_heading = True
+        label = f"{x['card']}: {x['title']}" if x["card"] else x["title"]
+        lines.append(f"[{x['kind']}] {label}")
+        lines.append(f"  {x['reason']}")
+        lines += [f"  $ {c}" for c in x["commands"]]
+    lines.append("Commands with --lead-secret run only in the lead session; never give the secret to an agent.")
+    return "\n".join(lines)
+
+
+def _setup(p):
+    p.add_argument("--kind", default=None, choices=KINDS, help="only this kind of item")
+    p.add_argument("--no-apply-check", action="store_true", help="skip the git apply checks for done cards")
+
+
+def _handler(ctx, a):
+    r = collect(ctx.board, check_apply=not a.no_apply_check)
+    if a.kind:
+        r = {**r, "items": [x for x in r["items"] if x["kind"] == a.kind]}
+        r["total"] = len(r["items"])
+    return r, render(r)
+
+
+def register_cli(add_command):
+    add_command("approvals", "everything waiting for a human, with copy-ready commands", _setup, _handler)