raidlock 0.1.0__py3-none-any.whl

raidlock/mcp/tools.py

@@ -0,0 +1,178 @@
+import os
+
+from ..core import Board, repos
+from ..core.errors import IdentityError, Precondition
+from ..core.transcript import _clean
+
+ID = {"type": "string"}
+FENCE = {"type": "integer"}
+
+
+def _schema(required, **props):
+    return {"type": "object", "properties": props, "required": list(required)}
+
+
+TOOLS = [
+    {
+        "name": "claimable",
+        "description": "Cards you can claim now, and why others are blocked.",
+        "inputSchema": _schema(()),
+    },
+    {
+        "name": "claim",
+        "description": "Take a card: lock its paths. Returns the fence.",
+        "inputSchema": _schema(("id",), id=ID),
+    },
+    {
+        "name": "heartbeat",
+        "description": "Renew your lease on a card.",
+        "inputSchema": _schema(("id",), id=ID, fence=FENCE),
+    },
+    {
+        "name": "note",
+        "description": "Add a one-line progress note; renews the lease.",
+        "inputSchema": _schema(("id", "text"), id=ID, text={"type": "string"}, fence=FENCE),
+    },
+    {
+        "name": "lock",
+        "description": "Add lock paths (<repo>/<path>, comma-separated) to your card.",
+        "inputSchema": _schema(("id", "paths"), id=ID, paths={"type": "string"}, fence=FENCE),
+    },
+    {
+        "name": "move",
+        "description": "Move your card to review or blocked. Only the lead closes cards.",
+        "inputSchema": _schema(
+            ("id", "lane"), id=ID, lane={"enum": ["review", "blocked"]}, note={"type": "string"}, fence=FENCE
+        ),
+    },
+    {
+        "name": "msg",
+        "description": "Message an agent; card ties it to a task.",
+        "inputSchema": _schema(("to", "text"), to={"type": "string"}, text={"type": "string"}, card=ID),
+    },
+    {"name": "inbox", "description": "Read your new messages.", "inputSchema": _schema(())},
+]
+
+
+def _annotations(name):
+    if name == "claimable":
+        return {"readOnlyHint": True, "openWorldHint": False}
+    return {
+        "readOnlyHint": False,
+        "destructiveHint": False,
+        "idempotentHint": name == "heartbeat",
+        "openWorldHint": False,
+    }
+
+
+for tool in TOOLS:
+    tool["annotations"] = _annotations(tool["name"])
+SPECS = {t["name"]: t["inputSchema"] for t in TOOLS}
+LEAD_REFUSAL = "the MCP server never acts as the lead; the lead uses the raidlock CLI"
+
+
+class Session:
+    def __init__(self, board_path=None, env=None):
+        base = dict(os.environ if env is None else env)
+        base.pop("RAIDLOCK_ROLE", None)
+        self.env = base
+        self.board_path = board_path
+        self.fences = {}
+
+    def board(self):
+        return Board.open(self.board_path, env=self.env)
+
+    def caller(self, board, card=None, fence=None):
+        if fence is None and card:
+            fence = self.fences.get(card)
+        c = board.caller(fence=fence, env=self.env)
+        if c.is_lead or (c.name and c.name == board.lead):
+            raise IdentityError(LEAD_REFUSAL, agent=c.name, hint="set RAIDLOCK_AGENT and RAIDLOCK_TOKEN to a worker")
+        return c
+
+    def call(self, name, args):
+        check_args(name, args)
+        board = self.board()
+        return _clean(getattr(self, "t_" + name)(board, args))
+
+    def t_claimable(self, b, a):
+        c = self.caller(b)
+        ready, waiting = [], []
+        for cid, v in sorted(b.claimable(agent=c.name or None).items()):
+            if v["ok"]:
+                ready.append({"id": cid, "title": v["title"], **({"takeover": v["takeover"]} if v["takeover"] else {})})
+            else:
+                waiting.append({"id": cid, "why": "; ".join(v["reasons"])})
+        return {"ready": ready, "blocked": waiting}
+
+    def t_claim(self, b, a):
+        r = b.claim(a["id"], self.caller(b), checkout=os.getcwd() if repos.find_root(os.getcwd()) else None)
+        self.fences[a["id"]] = r["fence"]
+        return {"card": r["card"], "fence": r["fence"], "expires": r["expires"], "paths": r["paths"]}
+
+    def t_heartbeat(self, b, a):
+        r = b.heartbeat(a["id"], self.caller(b, a["id"], a.get("fence")))
+        return {"card": r["card"], "expires": r["expires"], **({"resumed": True} if r.get("resumed") else {})}
+
+    def t_note(self, b, a):
+        b.note(a["id"], self.caller(b, a["id"], a.get("fence")), a["text"])
+        return {"card": a["id"], "noted": True}
+
+    def t_lock(self, b, a):
+        r = b.lock_paths(a["id"], self.caller(b, a["id"], a.get("fence")), a["paths"])
+        return {"card": r["card"], "locks": r["locks"]}
+
+    def t_move(self, b, a):
+        if a["lane"] not in ("review", "blocked"):
+            raise Precondition("move takes review or blocked", lane=a["lane"])
+        r = b.move(a["id"], a["lane"], self.caller(b, a["id"], a.get("fence")), note=a.get("note"))
+        return {"card": r["card"], "lane": r["lane"]}
+
+    def t_msg(self, b, a):
+        m = b.send(self.caller(b), a["to"], a["text"], task=a.get("card") or None)
+        out = {"to": a["to"], "status": m.get("status", "")}
+        if m.get("dropped"):
+            out["dropped"] = True
+        return out
+
+    def t_inbox(self, b, a):
+        r = b.inbox(self.caller(b))
+        msgs = [
+            {
+                k: v
+                for k, v in (
+                    ("from", m.get("from")),
+                    ("card", m.get("task")),
+                    ("sent", m.get("sent")),
+                    ("text", m.get("text")),
+                )
+                if v
+            }
+            for m in r["messages"]
+        ]
+        out = {"messages": msgs}
+        if r.get("queued"):
+            out["queued"] = r["queued"]
+        return out
+
+
+def check_args(name, args):
+    spec = SPECS[name]
+    if not isinstance(args, dict):
+        raise Precondition("arguments must be an object")
+    extra = sorted(set(args) - set(spec["properties"]))
+    if extra:
+        raise Precondition(f"unknown argument(s): {', '.join(extra)}", tool=name)
+    for key in spec["required"]:
+        if key not in args:
+            raise Precondition(f"missing argument: {key}", tool=name)
+    for key, value in args.items():
+        prop = spec["properties"][key]
+        if "enum" in prop:
+            if value not in prop["enum"]:
+                raise Precondition(f"{key} must be one of {', '.join(prop['enum'])}", tool=name)
+        elif prop["type"] == "integer":
+            if isinstance(value, bool) or not isinstance(value, int):
+                raise Precondition(f"{key} must be an integer", tool=name)
+        elif not isinstance(value, str) or not value.strip():
+            raise Precondition(f"{key} must be a non-empty string", tool=name)

raidlock/notify.py

@@ -0,0 +1,144 @@
+import base64
+import datetime
+import shutil
+import subprocess
+import sys
+import time
+from xml.sax.saxutils import escape
+
+from .core import db
+
+
+def send_notification(title, body):
+    if sys.platform == "darwin":
+        executable = shutil.which("terminal-notifier")
+        if executable:
+            command = [executable, "-title", title, "-message", body]
+        else:
+            executable = shutil.which("osascript")
+            if not executable:
+                return False
+            script = "on run argv\ndisplay notification (item 2 of argv) with title (item 1 of argv)\nend run"
+            command = [executable, "-e", script, title, body]
+    elif sys.platform == "win32":
+        executable = shutil.which("powershell") or shutil.which("pwsh")
+        if not executable:
+            return False
+        xml = (
+            '<toast><visual><binding template="ToastGeneric"><text>'
+            + escape(title)
+            + "</text><text>"
+            + escape(body)
+            + "</text></binding></visual></toast>"
+        )
+        payload = base64.b64encode(xml.encode("utf-8")).decode("ascii")
+        script = (
+            "[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, "
+            "ContentType = WindowsRuntime] > $null; "
+            "[Windows.Data.Xml.Dom.XmlDocument, Windows.Data.Xml.Dom.XmlDocument, "
+            "ContentType = WindowsRuntime] > $null; "
+            "$xml = New-Object Windows.Data.Xml.Dom.XmlDocument; "
+            f'$xml.LoadXml([Text.Encoding]::UTF8.GetString([Convert]::FromBase64String("{payload}"))); '
+            "$toast = [Windows.UI.Notifications.ToastNotification]::new($xml); "
+            '[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier("Raidlock").Show($toast)'
+        )
+        encoded = base64.b64encode(script.encode("utf-16le")).decode("ascii")
+        command = [executable, "-NoProfile", "-NonInteractive", "-EncodedCommand", encoded]
+    elif sys.platform.startswith("linux"):
+        executable = shutil.which("notify-send")
+        if not executable:
+            return False
+        command = [executable, "--", title, body]
+    else:
+        return False
+    try:
+        return subprocess.run(command, capture_output=True, timeout=10, check=False).returncode == 0
+    except (OSError, subprocess.SubprocessError):
+        return False
+
+
+def _parse_time(value):
+    try:
+        parsed = datetime.datetime.fromisoformat(value.replace("Z", "+00:00"))
+        return parsed.replace(tzinfo=datetime.UTC) if parsed.tzinfo is None else parsed
+    except (AttributeError, TypeError, ValueError):
+        return None
+
+
+class Watcher:
+    def __init__(self, board, notify=None, debounce=60):
+        self.board = board
+        self.notify = notify or send_notification
+        self.debounce = debounce
+        self.version = None
+        self.cursor = 0
+        self.cards = []
+        self.leases = {}
+        self.active = set()
+        self.sent = {}
+
+    def poll(self, now=None, monotonic=None):
+        now = now or datetime.datetime.now(datetime.UTC)
+        tick = time.monotonic() if monotonic is None else monotonic
+        version = self.board.version()
+        if version != self.version:
+            self.cards = self.board.cards()
+            self.leases = self.board.leases()
+            self.version = version
+        events = []
+        active = set()
+        for card in self.cards:
+            cid = card["id"]
+            if card["lane"] == "review":
+                key = ("review", cid)
+                active.add(key)
+                events.append((key, "Card entered review", f"{cid}: {card['title']}"))
+        for cid, lease in self.leases.items():
+            expires = _parse_time(lease.get("expires"))
+            if expires and 0 < (expires - now).total_seconds() < 300:
+                key = ("lease", cid, lease.get("fence"), lease.get("expires"))
+                active.add(key)
+                events.append((key, "Lease expires soon", f"{cid}: {lease.get('agent', '')} (under 5 minutes)"))
+        for name, status in self.board.statuses().items():
+            if status["status"] == "stalled":
+                key = ("stalled", name, status.get("card", ""))
+                active.add(key)
+                events.append((key, "Agent stalled", f"{name}: {status.get('card', '')}"))
+        for record in self.board.transcript.read(since=self.cursor):
+            self.cursor = max(self.cursor, record["seq"])
+            if record.get("kind") == "msg" and record.get("to") == self.board.lead:
+                key = ("message", record.get("messageId", record["seq"]))
+                body = "\n".join(p.get("text", "") for p in record.get("parts", []) if p.get("kind") == "text")
+                events.append((key, "Message to lead", body))
+        delivered = 0
+        for key, title, body in events:
+            if key in self.active or tick - self.sent.get(key, float("-inf")) < self.debounce:
+                continue
+            self.sent[key] = tick
+            delivered += bool(self.notify(f"Raidlock: {title}", body))
+        self.active = active
+        self.sent = {key: value for key, value in self.sent.items() if tick - value < self.debounce}
+        return delivered
+
+
+def _setup(parser):
+    parser.add_argument("--once", action="store_true", help="Check current events once and exit")
+
+
+def _handle(ctx, args):
+    watcher = Watcher(ctx.board)
+    count = 0
+    try:
+        while True:
+            count += watcher.poll()
+            if args.once:
+                break
+            db.close_all()
+            time.sleep(2)
+    except KeyboardInterrupt:
+        pass
+    return {"notifications": count}, ""
+
+
+def register_cli(add_command):
+    add_command("notify", "watch the board for desktop notifications", _setup, _handle)

raidlock/party.py

@@ -0,0 +1,239 @@
+"""Raid-theme party roles, boss board and loot, derived from recorded card activity on every read. Display only:
+nothing is stored and nothing is granted. Item names are original to raidlock.
+
+Tank counts leases held now on blocked cards plus claimed cards that were blocked or that other cards depend on. Healer
+counts reviews and passing verify runs on other agents' cards plus moving someone else's card out of blocked. DPS counts
+finished cards the agent owns and leases held now on cards that are not blocked. The highest score wins; ties go to DPS,
+then Tank, then Healer. Agents with no activity get no role. Cancelled cards never count.
+
+A boss is a card with BOSS_DEPENDENTS or more transitive dependents, or one the lead marked with edit --boss on. Its HP
+is the share of the boss and its dependents still open; it is slain when all of them are done. Every done card drops one
+item for its owner; the rarity comes from dependents, changes-requested reviews, a first-try verify pass and recorded
+run time, and the name from a hash of the card id, so the same card always drops the same item.
+"""
+
+import datetime
+import hashlib
+
+from .core import clock
+from .web.replay import data_of, history
+
+ROLES = ("dps", "tank", "healer")
+BOSS_DEPENDENTS = 3
+RARITIES = ("Common", "Uncommon", "Rare", "Epic", "Legendary")
+ADJECTIVES = (
+    ("Worn", "Patched", "Sturdy", "Plain"),
+    ("Polished", "Tempered", "Keen", "Lucky"),
+    ("Runed", "Moonlit", "Gilded", "Whispering"),
+    ("Stormbound", "Emberforged", "Starlit", "Thornwoven"),
+    ("Sunforged", "Everflame", "Worldroot", "Firstlight"),
+)
+NOUNS = (
+    "Lantern",
+    "Whetstone",
+    "Cloak",
+    "Compass",
+    "Quill",
+    "Buckler",
+    "Satchel",
+    "Ring",
+    "Spyglass",
+    "Hammer",
+    "Amulet",
+    "Boots",
+)
+
+
+def live(cards):
+    return [c for c in cards if c.get("lane") != "cancelled"]
+
+
+def dependents(cards):
+    ids = {c["id"] for c in cards}
+    back = {cid: set() for cid in ids}
+    for c in cards:
+        for dep in c.get("depends", []):
+            if dep in back and dep != c["id"]:
+                back[dep].add(c["id"])
+    out = {}
+    for cid in sorted(ids):
+        seen, stack = set(), sorted(back[cid])
+        while stack:
+            nxt = stack.pop()
+            if nxt == cid or nxt in seen:
+                continue
+            seen.add(nxt)
+            stack.extend(sorted(back[nxt]))
+        out[cid] = seen
+    return out
+
+
+def _claimers(card):
+    out = set()
+    for n in card.get("notes", []):
+        words = str(n.get("text", "")).split()
+        if len(words) >= 3 and words[:2] == ["claimed", "by"]:
+            out.add(words[2])
+    return out
+
+
+def _unblockers(card):
+    out, lane = [], ""
+    for n in card.get("notes", []):
+        text = str(n.get("text", ""))
+        if not text.startswith("-> "):
+            continue
+        nxt = text[3:].split(" ", 1)[0]
+        if lane == "blocked" and nxt != "blocked":
+            out.append(n.get("by", ""))
+        lane = nxt
+    return out
+
+
+def roles(board):
+    cards = live(board.cards())
+    names = sorted(board.agents())
+    score = {n: dict.fromkeys(ROLES, 0) for n in names}
+    deps = dependents(cards)
+
+    def add(name, role):
+        if name in score:
+            score[name][role] += 1
+
+    lanes = {c["id"]: c.get("lane") for c in cards}
+    for lease in sorted(board.leases().values(), key=lambda x: x.get("card", "")):
+        add(lease.get("agent", ""), "tank" if lanes.get(lease.get("card")) == "blocked" else "dps")
+    for c in cards:
+        owner = c.get("owner", "")
+        hard = deps.get(c["id"]) or any(str(n.get("text", "")).startswith("-> blocked") for n in c.get("notes", []))
+        if hard:
+            for name in _claimers(c):
+                add(name, "tank")
+        if c.get("lane") == "done" and owner:
+            add(owner, "dps")
+        for r in c.get("reviews", []):
+            if r.get("verdict") in ("approve", "changes") and r.get("by") != owner:
+                add(r.get("by", ""), "healer")
+        for v in c.get("verifications", []):
+            if v.get("passed") and v.get("by") != owner:
+                add(v.get("by", ""), "healer")
+        for name in _unblockers(c):
+            if name != owner:
+                add(name, "healer")
+    out = {}
+    for name in names:
+        s = score[name]
+        best = max(ROLES, key=lambda r: (s[r], -ROLES.index(r)))
+        out[name] = {"role": best if s[best] else "", **s}
+    return out
+
+
+def _done_at(board):
+    out = {}
+    for r in history(board)[0]:
+        if r.get("kind") == "status" and data_of(r).get("lane") == "done" and r.get("taskId"):
+            out[r["taskId"]] = r.get("ts", "")
+    return out
+
+
+def bosses(cards, deps, done_at):
+    by_id = {c["id"]: c for c in cards}
+    out = []
+    for cid in sorted(by_id):
+        under = deps.get(cid, set())
+        if len(under) < BOSS_DEPENDENTS and not by_id[cid].get("boss"):
+            continue
+        group = [cid, *sorted(under)]
+        still = [x for x in group if by_id[x].get("lane") != "done"]
+        slain = not still
+        out.append(
+            {
+                "id": cid,
+                "title": by_id[cid].get("title", cid),
+                "dependents": len(under),
+                "total": len(group),
+                "open": len(still),
+                "hp": round(100 * len(still) / len(group)),
+                "slain": slain,
+                "slain_at": max(done_at.get(x) or by_id[x].get("updated", "") for x in group) if slain else "",
+                "final": by_id[max(group, key=lambda x: done_at.get(x) or by_id[x].get("updated", ""))].get("owner", "")
+                if slain
+                else "",
+            }
+        )
+    alive = sorted((b for b in out if not b["slain"]), key=lambda b: (-b["hp"], b["id"]))
+    dead = sorted((b for b in out if b["slain"]), key=lambda b: (b["slain_at"], b["id"]), reverse=True)
+    return alive + dead
+
+
+def tier(card, dependents):
+    changes = sum(1 for r in card.get("reviews", []) if r.get("verdict") == "changes")
+    runs = card.get("verifications") or []
+    first_pass = bool(runs) and bool(runs[0].get("passed"))
+    hours = sum(int(r.get("duration_ms") or 0) for r in card.get("costs", [])) / 3600000.0
+    score = min(dependents, 4) + min(changes, 2) + int(first_pass) + (2 if hours >= 4 else 1 if hours >= 1 else 0)
+    return min(4, (score + 1) // 2)
+
+
+def item_name(card_id, rank):
+    digest = hashlib.sha256(f"{card_id}\n{rank}".encode()).digest()
+    words = ADJECTIVES[rank]
+    return f"{words[digest[0] % len(words)]} {NOUNS[digest[1] % len(NOUNS)]}"
+
+
+def loot(cards, deps, done_at):
+    bags = {}
+    for c in cards:
+        if c.get("lane") != "done" or not c.get("owner"):
+            continue
+        rank = tier(c, len(deps.get(c["id"], ())))
+        bags.setdefault(c["owner"], []).append(
+            {
+                "card": c["id"],
+                "title": c.get("title", c["id"]),
+                "item": item_name(c["id"], rank),
+                "rarity": RARITIES[rank],
+                "tier": rank,
+                "at": done_at.get(c["id"]) or c.get("updated", ""),
+            }
+        )
+    out = []
+    for name, items in sorted(bags.items()):
+        out.append({"agent": name, "items": sorted(items, key=lambda i: (i["at"], i["card"]))})
+    return out
+
+
+def payload(board, query):
+    cards = live(board.cards())
+    deps = dependents(cards)
+    done_at = _done_at(board)
+    return {
+        "bosses": bosses(cards, deps, done_at),
+        "bags": loot(cards, deps, done_at),
+        "boss_dependents": BOSS_DEPENDENTS,
+    }
+
+
+def slain_bosses(cards):
+    cards = live(cards)
+    return [
+        {k: b[k] for k in ("id", "title", "total", "final", "slain_at")}
+        for b in bosses(cards, dependents(cards), {})
+        if b["slain"]
+    ]
+
+
+def streak(cards, today=None):
+    days = set()
+    for c in cards:
+        when = clock.parse(c.get("updated", "")) if c.get("lane") == "done" else None
+        if when:
+            days.add(when.astimezone().date())
+    day = today or datetime.datetime.now().astimezone().date()
+    if day not in days:
+        day -= datetime.timedelta(days=1)
+    count = 0
+    while day in days:
+        count += 1
+        day -= datetime.timedelta(days=1)
+    return count