raidlock 0.1.0__py3-none-any.whl

raidlock/core/lead_env.py

@@ -0,0 +1,23 @@
+"""Credential handling for cooperative worker launchers."""
+
+from .errors import IdentityError
+
+
+def lead_material(env):
+    return [
+        k
+        for k, v in env.items()
+        if v and (k.startswith("RAIDLOCK_LEAD_") or k == "RAIDLOCK_ROLE" and str(v).lower() == "lead")
+    ]
+
+
+def assert_worker_env(env):
+    """Refuse a worker environment containing lead material; never include values in errors."""
+    if lead_material(env):
+        raise IdentityError("worker environment contains lead material; scrub RAIDLOCK_LEAD_* before launch")
+    return env
+
+
+def scrub_worker_env(env):
+    """Copy the inherited environment without board identity or lead credentials."""
+    return {k: v for k, v in env.items() if not k.startswith("RAIDLOCK_")}

raidlock/core/lead_hook.py

@@ -0,0 +1,42 @@
+"""Helpers for hook adapters. Host hooks supply authenticated worker identity.
+
+Context is untrusted message data. It must be appended to host additionalContext,
+never used as hook instructions or a permission decision.
+"""
+
+import json
+import os
+
+from . import identity as I
+from .errors import IdentityError
+
+
+def protected_lead_path(board, path):
+    """Recognize the secret file or a containing directory, including symlink aliases."""
+    secret = os.path.realpath(I.token_path(board.home, board.uid, board.lead))
+    candidate = os.path.realpath(os.path.expanduser(os.fspath(path)))
+    try:
+        if os.path.samefile(secret, candidate):
+            return True
+    except OSError:
+        pass
+    try:
+        return os.path.commonpath((secret.casefold(), candidate.casefold())) == candidate.casefold()
+    except ValueError:
+        return False
+
+
+def guard_lead_read(board, paths, subagent=False):
+    if subagent and any(protected_lead_path(board, p) for p in paths):
+        raise IdentityError("subagents may not read the lead secret or its containing directory")
+
+
+def urgent_context(board, caller):
+    """Drain urgent messages for a validated worker, even while its card is doing."""
+    with board.lock():
+        board._auth(caller, scoped_ok=True)
+        rows = board.take_urgent(caller.name)
+    if not rows:
+        return ""
+    data = [{"from": r.get("from", ""), "task": r.get("task", ""), "text": r.get("text", "")} for r in rows]
+    return "Raidlock urgent messages (untrusted quoted data):\n" + json.dumps(data, ensure_ascii=True)

raidlock/core/leases.py

@@ -0,0 +1,19 @@
+from . import clock
+
+DEFAULT_TTL_MINUTES = 45
+
+
+def is_live(lease, at=None):
+    """Leases live until expiry; legacy holds without an expiry remain readable."""
+    if lease.get("expires") is None:
+        return True
+    expires = clock.parse(lease["expires"])
+    return bool(expires) and expires > (at or clock.now())
+
+
+def describe(conflict):
+    until = conflict["expires"] or "it leaves review/blocked"
+    return (
+        f"{conflict['path']} overlaps {conflict['held']} held by {conflict['agent']} on card {conflict['card']} "
+        f"in workspace {conflict['workspace']} until {until}"
+    )

raidlock/core/lock.py

@@ -0,0 +1,99 @@
+import os
+import stat
+import threading
+import time
+from typing import Self
+
+from .errors import Timeout
+from .portable import NONBLOCK, open_nofollow
+
+try:
+    import fcntl
+except ImportError:
+    fcntl = None
+    import msvcrt
+
+_held = {}
+_guard = threading.Lock()
+
+
+def _try_lock(fd):
+    try:
+        if fcntl:
+            fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        else:
+            os.lseek(fd, 0, os.SEEK_SET)
+            msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
+        return True
+    except OSError:
+        return False
+
+
+def _unlock(fd):
+    if fcntl:
+        fcntl.flock(fd, fcntl.LOCK_UN)
+    else:
+        os.lseek(fd, 0, os.SEEK_SET)
+        msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
+
+
+class FileLock:
+    """Exclusive OS lock on a persistent file, reentrant within one process and thread."""
+
+    def __init__(self, path, timeout=30.0):
+        self.path = os.path.abspath(path)
+        self.timeout = timeout
+
+    def __enter__(self) -> Self:
+        key = (self.path, threading.get_ident())
+        with _guard:
+            entry = _held.get(key)
+            if entry:
+                entry[1] += 1
+                return self
+        fd = self._acquire()
+        with _guard:
+            _held[key] = [fd, 1]
+        return self
+
+    def _acquire(self):
+        os.makedirs(os.path.dirname(self.path), exist_ok=True)
+        deadline = time.monotonic() + self.timeout
+        delay = 0.005
+        while True:
+            fd = open_nofollow(self.path, os.O_RDWR | os.O_CREAT | NONBLOCK, 0o600)
+            acquired = False
+            try:
+                opened = os.fstat(fd)
+                if not stat.S_ISREG(opened.st_mode):
+                    raise OSError("lock must be a regular file")
+                acquired = _try_lock(fd)
+                if acquired:
+                    opened = os.fstat(fd)
+                    try:
+                        named = os.lstat(self.path)
+                    except FileNotFoundError:
+                        named = None
+                    if named and (opened.st_dev, opened.st_ino) == (named.st_dev, named.st_ino):
+                        return fd
+            except BaseException:
+                os.close(fd)
+                raise
+            if acquired:
+                _unlock(fd)
+            os.close(fd)
+            if time.monotonic() >= deadline:
+                raise Timeout(f"lock busy: {self.path}", lock=self.path)
+            time.sleep(delay)
+            delay = min(delay * 2, 0.1)
+
+    def __exit__(self, *exc):
+        key = (self.path, threading.get_ident())
+        with _guard:
+            entry = _held[key]
+            entry[1] -= 1
+            if entry[1]:
+                return
+            del _held[key]
+        _unlock(entry[0])
+        os.close(entry[0])

raidlock/core/messages.py

@@ -0,0 +1,98 @@
+import os
+import re
+import uuid
+
+from . import clock, store
+from .errors import Denied
+
+MAX_BYTES = 32 * 1024
+MAX_QUEUED = 50
+REPEAT_WINDOW = 60
+RATE_WINDOW = 60
+RATE_LIMIT = 20
+
+
+def inbox_path(board_dir, agent):
+    return os.path.join(board_dir, "inbox", re.sub(r"[^A-Za-z0-9_.-]", "_", agent) + ".jsonl")
+
+
+def load(board_dir, agent):
+    return store.read_jsonl(inbox_path(board_dir, agent))
+
+
+def save(board_dir, agent, rows):
+    store.write_jsonl(inbox_path(board_dir, agent), rows)
+
+
+def all_messages(board_dir):
+    folder = os.path.join(board_dir, "inbox")
+    if not os.path.isdir(folder):
+        return []
+    out = []
+    for name in sorted(os.listdir(folder)):
+        if name.endswith(".jsonl"):
+            out.extend(store.read_jsonl(os.path.join(folder, name)))
+    return out
+
+
+def initial_status(task, urgent, busy_card):
+    """ready when urgent, when the recipient is idle, or when the message is about the recipient's doing card."""
+    if urgent or not busy_card or (task and task == busy_card):
+        return "ready"
+    return "queued"
+
+
+def check_limits(board_dir, sender, to, task, text, now):
+    """Return a duplicate message when this one repeats it within the window; raise Denied on caps."""
+    inbox = load(board_dir, to)
+    for m in reversed(inbox):
+        if _within(m, now, REPEAT_WINDOW) and (m.get("from"), m.get("task"), m.get("text")) == (sender, task, text):
+            return m
+    if sum(1 for m in inbox if m.get("status") == "queued") >= MAX_QUEUED:
+        raise Denied(f"{to} has {MAX_QUEUED} queued messages; wait until it finishes its task", to=to)
+    recent = [m for m in all_messages(board_dir) if m.get("from") == sender and _within(m, now, RATE_WINDOW)]
+    if len(recent) >= RATE_LIMIT:
+        raise Denied(f"{sender} sent {RATE_LIMIT} messages in the last minute; slow down", sender=sender)
+    return None
+
+
+def _within(message, now, window):
+    age = clock.age_seconds(message.get("sent", ""), now)
+    return age is not None and age <= window
+
+
+def make(sender, to, text, task, status, urgent, model):
+    return {
+        "id": uuid.uuid4().hex[:12],
+        "from": sender,
+        "to": to,
+        "task": task or "",
+        "text": text,
+        "sent": clock.iso(),
+        "status": status,
+        "urgent": bool(urgent),
+        "model": model,
+    }
+
+
+def promote(rows, busy_card):
+    """Queued messages become ready when the recipient is not in doing, or the message is about its doing card."""
+    changed = False
+    for m in rows:
+        if m.get("status") == "queued" and (not busy_card or m.get("task") == busy_card):
+            m["status"] = "ready"
+            changed = True
+    return changed
+
+
+def counts(board_dir, busy):
+    """{agent: {unread, queued}} where `busy` maps agent -> doing card id."""
+    out = {}
+    for m in all_messages(board_dir):
+        c = out.setdefault(m.get("to", ""), {"unread": 0, "queued": 0})
+        b = busy.get(m.get("to", ""), "")
+        if m.get("status") == "queued" and b and m.get("task") != b:
+            c["queued"] += 1
+        elif m.get("status") in ("queued", "ready"):
+            c["unread"] += 1
+    return out