continuity-guard 0.5.0__py3-none-any.whl

continuity_guard/__init__.py

@@ -0,0 +1,14 @@
+"""Continuity Guard -- liveness and progress watchdog for long-running AI agent sessions.
+
+    from continuity_guard import guard
+
+    with guard("nightly-refactor", profile="overnight") as s:
+        for step in agent.run():
+            s.progress(step=step.name, tool=step.tool,
+                       args=step.args, tokens=step.tokens)
+"""
+
+from .client import Session, args_hash, guard
+
+__all__ = ["guard", "Session", "args_hash", "__version__"]
+__version__ = "0.5.0"

continuity_guard/actions.py

@@ -0,0 +1,230 @@
+"""Actions and notifications.
+
+Kill authority lives here, and only here, and only locally. Three ways to get
+termination wrong, all guarded against:
+
+  PID reuse       -> pidfd where available, else PID+start_time verified as a pair
+  orphaned kids   -> kill the process GROUP, not the process
+  no grace        -> SIGTERM, wait, SIGKILL
+"""
+
+from __future__ import annotations
+
+import errno
+import os
+import signal
+import subprocess
+import time
+import urllib.request
+
+
+# ---------------------------------------------------------------- termination
+# Can this platform give us a process start time at all? Decided once, from
+# our own PID: if we cannot read our own, we cannot read anyone's.
+def _probe_start_time_support() -> bool:
+    try:
+        with open(f"/proc/{os.getpid()}/stat", "rb") as fh:
+            data = fh.read()
+        int(data[data.rindex(b")") + 2:].split()[19])
+        return True
+    except Exception:
+        return False
+
+
+def _start_time(pid: int) -> int:
+    try:
+        with open(f"/proc/{pid}/stat", "rb") as fh:
+            data = fh.read()
+        return int(data[data.rindex(b")") + 2 :].split()[19])
+    except Exception:
+        return 0
+
+
+def _alive(pid: int) -> bool:
+    """Is this PID a live process -- not a zombie?
+
+    /proc/<pid> keeps existing after a process dies, right up until its parent
+    reaps it. An existence check alone therefore reads a corpse as alive. That
+    matters on the supervisor path: cg_supervise is the PARENT of the agent it
+    registers, so a terminated agent sits as a zombie until the supervisor's
+    wait() runs. The grace loop would spin the full window and then fire a
+    pointless SIGKILL at an already-dead process -- and report
+    "SIGKILL after 20s grace" when SIGTERM had in fact worked immediately.
+    """
+    try:
+        with open(f"/proc/{pid}/stat", "rb") as fh:
+            data = fh.read()
+        # comm (field 2) may contain spaces and parens: parse after the last ')'
+        return data[data.rindex(b")") + 2:].split()[0] != b"Z"
+    except (OSError, ValueError, IndexError):
+        return False
+
+
+def _identity_ok(pid: int, expected_start: int) -> bool:
+    """A PID alone is not an identity. Recorded an hour ago it may belong to
+    something else entirely by now.
+
+    A missing start_time used to fall back to "is anything alive with this
+    PID", which is not an identity check at all -- it accepts every live
+    process on the box. Combined with a world-writable socket and peer-supplied
+    policy, that made an armed daemon a process-kill oracle: announce someone
+    else's PID with start_time 0, set a policy that terminates immediately, and
+    the daemon signals it. Termination now REQUIRES a verified start_time, and
+    an unverifiable identity is refused rather than assumed.
+    """
+    if pid <= 1:
+        return False
+    if expected_start:
+        return _start_time(pid) == expected_start
+    # No start_time was announced. This used to fall back to "is anything
+    # alive with this PID", which is not an identity check -- it accepts every
+    # live process on the box, and with peer-supplied policy that made an armed
+    # daemon a process-kill oracle. Where the platform CAN supply a start time,
+    # its absence now means the identity is unverifiable and the kill is
+    # refused. Where it cannot (no /proc: macOS, Windows), refusing outright
+    # would silently disable armed termination on a supported platform, so the
+    # weaker check stands there and the daemon says so at startup.
+    if _START_TIME_AVAILABLE:
+        return False
+    return _alive(pid)
+
+
+_START_TIME_AVAILABLE = _probe_start_time_support()
+
+
+def alive(pid: int) -> bool:
+    """Public liveness check: is this PID a running, non-zombie process?"""
+    return _alive(pid)
+
+
+def _ppid(pid: int) -> int:
+    try:
+        with open(f"/proc/{pid}/stat", "rb") as fh:
+            data = fh.read()
+        return int(data[data.rindex(b")") + 2:].split()[1])
+    except Exception:
+        return 0
+
+
+def is_descendant(pid: int, ancestor: int, max_depth: int = 40) -> bool:
+    """Is `pid` inside `ancestor`'s process tree?
+
+    A supervisor announcing a child is legitimate and common (cg_supervise does
+    exactly this), so the announced PID need not be the connecting peer. It
+    should, though, be a process that peer actually owns. Bounded walk: a
+    corrupted or cyclic chain must not spin.
+    """
+    if pid <= 1 or ancestor <= 1:
+        return False
+    seen, cur = set(), pid
+    for _ in range(max_depth):
+        if cur == ancestor:
+            return True
+        if cur in seen or cur <= 1:
+            return False
+        seen.add(cur)
+        cur = _ppid(cur)
+    return False
+
+
+def terminate(pid: int, start_time: int, grace: float = 20.0, log=print) -> str:
+    if not _identity_ok(pid, start_time):
+        return "skipped: pid identity mismatch (reuse guard)"
+
+    try:
+        pgid = os.getpgid(pid)
+    except OSError:
+        return "skipped: process gone"
+
+    # Only signal the group if it is genuinely the session's own group --
+    # otherwise we could take out the daemon or the user's shell.
+    target, how = (-pgid, "group") if pgid == pid else (pid, "process")
+
+    try:
+        os.kill(target, signal.SIGTERM)
+    except OSError as e:
+        if e.errno == errno.ESRCH:
+            return "already gone"
+        return f"SIGTERM failed: {e}"
+
+    deadline = time.monotonic() + grace
+    while time.monotonic() < deadline:
+        if not _alive(pid):
+            return f"terminated ({how}, SIGTERM)"
+        time.sleep(0.2)
+
+    try:
+        os.kill(target, signal.SIGKILL)
+    except OSError:
+        pass
+    return f"terminated ({how}, SIGKILL after {grace:g}s grace)"
+
+
+# --------------------------------------------------------------- notification
+def _notify_file(cfg, event, log):
+    path = os.path.expanduser(cfg.get("path", "~/continuity-guard-alerts.log"))
+    os.makedirs(os.path.dirname(path) or ".", exist_ok=True)
+    with open(path, "a") as fh:
+        fh.write(
+            "{ts} {level:<6} {name:<24} {detector:<12} {detail}{shadow}\n".format(
+                ts=time.strftime("%Y-%m-%dT%H:%M:%S"),
+                level=event["level"].upper(),
+                name=event["name"],
+                detector=event["detector"],
+                detail=event["detail"],
+                shadow="  [SHADOW]" if event["shadow"] else "",
+            )
+        )
+
+
+def _notify_exec(cfg, event, log):
+    cmd = cfg.get("command")
+    if not cmd:
+        return
+    env = dict(os.environ)
+    env.update({f"CG_{k.upper()}": str(v) for k, v in event.items()})
+    try:
+        subprocess.Popen(
+            cmd if isinstance(cmd, list) else ["/bin/sh", "-c", cmd],
+            env=env, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+            start_new_session=True,
+        )
+    except Exception as e:
+        log(f"notify exec failed: {e}")
+
+
+def _notify_webhook(cfg, event, log):
+    url = cfg.get("url")
+    if not url:
+        return
+    import json
+    body = json.dumps(event).encode("utf-8")
+    req = urllib.request.Request(
+        url, data=body, headers={"Content-Type": "application/json"}
+    )
+    try:
+        urllib.request.urlopen(req, timeout=float(cfg.get("timeout", 5)))
+    except Exception as e:
+        log(f"notify webhook failed: {e}")
+
+
+_KINDS = {"file": _notify_file, "exec": _notify_exec, "webhook": _notify_webhook}
+
+
+def notify(notifications, event, log=print):
+    """Fan out one event to every configured sink that subscribes to it.
+
+    Notification failures are logged and swallowed: a broken webhook must
+    never stop the daemon from doing its actual job.
+    """
+    for cfg in notifications or []:
+        wanted = cfg.get("on")
+        if wanted and event["level"] not in wanted and event["detector"] not in wanted:
+            continue
+        fn = _KINDS.get(cfg.get("kind"))
+        if not fn:
+            continue
+        try:
+            fn(cfg, event, log)
+        except Exception as e:
+            log(f"notify {cfg.get('kind')} failed: {e}")