loopbrake 0.1.0__py3-none-any.whl

loopbrake/__init__.py

@@ -0,0 +1,8 @@
+"""LoopBrake: stops stuck AI agent runs, with a guaranteed limit on stopping good ones."""
+
+__version__ = "0.1.0"
+
+from loopbrake.brake import Brake, Decision, start  # noqa: E402
+from loopbrake.calibration import calibrate  # noqa: E402
+
+__all__ = ["Brake", "Decision", "start", "calibrate", "__version__"]

loopbrake/agent_sdk.py

@@ -0,0 +1,84 @@
+"""Adapter for Claude's agent toolkit (`claude-agent-sdk`). Contract: specs/003-core-package/contracts/agent-sdk.md.
+
+Thin by design (constitution Principle V): it turns toolkit hook events into brake.step() calls and the
+brake's decision into the toolkit's stop reply. All stop logic lives in loopbrake.brake.
+"""
+import json
+import warnings
+
+from loopbrake.brake import start
+
+
+def _text(value):
+    """A tool's output as text: strings as they are, content blocks joined, anything else as JSON."""
+    if value is None:
+        return ""
+    if isinstance(value, str):
+        return value
+    if isinstance(value, list) and all(isinstance(b, dict) and "text" in b for b in value):
+        return "\n".join(b["text"] for b in value)
+    return json.dumps(value, sort_keys=True, ensure_ascii=False, default=str)
+
+
+class Hooks:
+    """One brake per session; a new user prompt starts a new run (as Claude Code turns are calibrated)."""
+
+    def __init__(self, project="default", home=None):
+        self.project, self.home, self.brakes, self._warned = project, home, {}, False
+
+    def _brake(self, session):
+        b = self.brakes.get(session)
+        if b is None or b.ended:
+            b = self.brakes[session] = start(self.project, session=session, home=self.home)
+        return b
+
+    async def user_prompt_submit(self, input_data, tool_use_id=None, context=None):
+        try:
+            session = input_data.get("session_id") or "default"
+            old = self.brakes.pop(session, None)
+            if old:
+                old.end()
+            self.brakes[session] = start(self.project, session=session, home=self.home)
+        except Exception as e:
+            self._fail(e)
+        return {}
+
+    async def post_tool_use(self, input_data, tool_use_id=None, context=None):
+        try:
+            tool = input_data.get("tool_name") or "tool"
+            action = f"{tool} {json.dumps(input_data.get('tool_input') or {}, sort_keys=True, ensure_ascii=False)}"
+            decision = self._brake(input_data.get("session_id") or "default").step(
+                action, _text(input_data.get("tool_response")), tool=tool)
+            if decision.stop:
+                return {"continue_": False, "stopReason": decision.reason}
+        except Exception as e:
+            self._fail(e)
+        return {}
+
+    async def stop(self, input_data, tool_use_id=None, context=None):
+        try:
+            b = self.brakes.pop(input_data.get("session_id") or "default", None)
+            if b:
+                b.end()
+        except Exception as e:
+            self._fail(e)
+        return {}
+
+    def _fail(self, e):
+        if not self._warned:
+            self._warned = True
+            warnings.warn(f"loopbrake: agent hook error ({e!r}); the agent continues unbraked", RuntimeWarning, stacklevel=2)
+
+
+def hooks(project="default", *, home=None):
+    """The `hooks=` value for ClaudeAgentOptions: UserPromptSubmit, PostToolUse and Stop."""
+    try:
+        from claude_agent_sdk import HookMatcher
+    except ImportError as e:
+        raise ImportError('loopbrake.agent_sdk needs the agent toolkit: pip install "loopbrake[agent-sdk]"') from e
+    h = Hooks(project, home)
+    return {
+        "UserPromptSubmit": [HookMatcher(hooks=[h.user_prompt_submit])],
+        "PostToolUse": [HookMatcher(hooks=[h.post_tool_use])],
+        "Stop": [HookMatcher(hooks=[h.stop])],
+    }

loopbrake/brake.py

@@ -0,0 +1,123 @@
+"""The brake: one per run. Stops a run once it goes past the stop line set from your own past
+successful runs, and says why. Contract: specs/003-core-package/contracts/python-api.md.
+
+v1's stop rule is the calibrated step budget (constitution 2.2.0). The stuck signals only explain.
+"""
+import uuid
+import warnings
+from typing import NamedTuple
+
+from loopbrake import calibration, records
+from loopbrake.signals import Step, method
+
+EXCERPT = 200
+
+
+class Decision(NamedTuple):
+    stop: bool
+    step: int
+    reason: str
+    watch_only: bool
+
+
+def _decide(steps, stop_line):
+    """The certified rule, unchanged from the experiments: stop when the `steps` score passes the line."""
+    # ponytail: rescores every step so far (O(t)) to call the certified scorer literally; about 0.1 ms
+    # at 250 steps. A running count is the upgrade, with tests/test_replay_data.py guarding agreement.
+    return stop_line is not None and method("steps")(steps)[-1][0] > stop_line
+
+
+class Brake:
+    def __init__(self, project, session, run, home, calibration, record=True):
+        self.project, self.session, self.run, self.home = project, session, run, home
+        self.calibration = calibration
+        line = calibration.get("stop_line") if calibration and not calibration.get("watch_only") else None
+        self.stop_line = line
+        self.watch_only = line is None
+        self.steps, self.stopped, self.reason, self.ended, self.tokens = [], False, "", False, None
+        self._warned = False
+        self._writer = records.RunWriter(home / "runs" / f"{session}.jsonl")
+        self._writer.on = record
+        cal = calibration or {}
+        self._record("run_start", project=project, calibration={
+            "method": "steps", "alpha": cal.get("alpha"), "n": cal.get("n"), "k": cal.get("k"),
+            "stop_line": self.stop_line, "watch_only": self.watch_only})
+
+    # ---- public ----
+
+    def step(self, action, result="", *, tool=None, tokens=None, error=None):
+        """Report one step. Returns a Decision; once it says stop, it keeps saying stop."""
+        try:
+            return self._step(action, result, tool, tokens, error)
+        except Exception as e:  # never hurt the host agent (spec FR-005)
+            self._fail(e)
+            return Decision(self.stopped, len(self.steps), self.reason, self.watch_only)
+
+    def end(self, status=None):
+        try:
+            if self.ended:
+                return
+            self.ended = True
+            status = status or ("stopped" if self.stopped else "finished")
+            self._record("run_end", status=status, steps=len(self.steps), tokens=self.tokens)
+        except Exception as e:
+            self._fail(e)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        self.end("stopped" if self.stopped else "interrupted" if exc_type else "finished")
+        return False
+
+    # ---- internals ----
+
+    def _step(self, action, result, tool, tokens, error):
+        action = str(action)
+        self.steps.append(Step(action, "" if result is None else str(result), error, int(tokens or 0)))
+        if tokens is not None:
+            self.tokens = (self.tokens or 0) + int(tokens)
+        t = len(self.steps)
+        self._record("step", step=t, tool=tool, action_excerpt=action[:EXCERPT], tokens=tokens, error=error)
+        if self.stopped:
+            return Decision(True, t, self.reason, False)
+        if _decide(self.steps, self.stop_line):
+            self.stopped = True
+            self.reason = self._explain(t)
+            self._record("stop", step=t, stop_line=self.stop_line, reason=self.reason)
+            return Decision(True, t, self.reason, False)
+        return Decision(False, t, "", self.watch_only)
+
+    def _explain(self, t):
+        cal = self.calibration or {}
+        reason = f"stopped at step {t}: past the stop line of {self.stop_line} steps"
+        if cal.get("n") and cal.get("alpha"):
+            reason += f" set from your {cal['n']} past successful runs (α {cal['alpha']:.0%})"
+        seen = method("max", lam=0.9)(self.steps)[-1][1]  # explains only; never decides
+        return f"{reason}; {seen}" if seen else reason
+
+    def _record(self, event, **fields):
+        self._writer.write({"event": event, "session": self.session, "run": self.run} | fields)
+
+    def _fail(self, e):
+        self.stop_line, self.watch_only = None, True
+        if not self._warned:
+            self._warned = True
+            warnings.warn(f"loopbrake: internal error ({e!r}); watching only for the rest of this run", RuntimeWarning, stacklevel=3)
+
+
+def replay(run, calibration):
+    """Feed a recorded run through a brake, writing no records. Returns the stop step, or None."""
+    b = Brake("replay", "replay", run.run, records.home(), calibration, record=False)
+    for s in run.steps:
+        if b.step(s.action, s.observation, tokens=s.tokens, error=s.error).stop:
+            return len(b.steps)
+    return None
+
+
+def start(project="default", *, session=None, run=None, home=None):
+    """Start one run. Missing or damaged calibration means watch-only, never an exception."""
+    if not records.valid_project(project):
+        raise ValueError(f"project names may use letters, digits, '.', '_' and '-' (got {project!r})")
+    h = records.home(home)
+    return Brake(project, session or uuid.uuid4().hex, run or uuid.uuid4().hex[:12], h, calibration.load(project, h))

loopbrake/calibration.py

@@ -0,0 +1,107 @@
+"""Calibration: set the stop line from your own past successful runs (constitution Principle I).
+
+Contract: specs/003-core-package/contracts/python-api.md and records.md.
+"""
+import hashlib
+import json
+import math
+import warnings
+from datetime import date
+from pathlib import Path
+
+from loopbrake import __version__, records
+from loopbrake.conformal import rank, threshold
+from loopbrake.traces import claude_code_turns, read_runs
+
+
+def path(project, home):
+    return home / "calibration" / f"{project}.json"
+
+
+def load(project, home):
+    """The calibration record for a project, or None if there is none or it is damaged (watch-only)."""
+    p = path(project, home)
+    if not p.exists():
+        return None
+    try:
+        rec = json.loads(p.read_text())
+        line = rec["stop_line"]
+        ok = (rec["method"] == "steps" and isinstance(rec["watch_only"], bool) and isinstance(rec["n"], int)
+              and 0 < rec["alpha"] < 1 and (line is None or (isinstance(line, int) and line >= 0)))
+        if not ok:
+            raise ValueError("unexpected values")
+        return rec
+    except Exception as e:
+        warnings.warn(f"loopbrake: calibration file {p} is damaged ({e}); watching only", RuntimeWarning, stacklevel=3)
+        return None
+
+
+def runs_needed(alpha):
+    """The fewest successful runs that give a stop line at this alpha (fewer means watch-only)."""
+    n = 1
+    while rank(n, alpha) > n:
+        n += 1
+    return n
+
+
+def _from_runs_file(src, exclude):
+    """One successful run per task (the first by run id), skipping excluded ids."""
+    runs, _ = read_runs(src)
+    first, seen, excluded = {}, 0, 0
+    for r in sorted(runs, key=lambda r: r.run):
+        if not r.steps:
+            continue
+        seen += 1
+        if r.run in exclude:
+            excluded += 1
+            continue
+        if r.success and r.task not in first:
+            first[r.task] = len(r.steps)
+    source = {"kind": "runs-file", "sha256": hashlib.sha256(src.read_bytes()).hexdigest(), "runs_seen": seen, "excluded": excluded}
+    return list(first.values()), source
+
+
+def _from_claude_code(folder, exclude):
+    """Every turn is its own task; success follows the experiments' rule (not interrupted, not excluded)."""
+    files = sorted(folder.glob("*.jsonl"))
+    if not files:
+        raise FileNotFoundError(f"no Claude Code session files (*.jsonl) in {folder}")
+    lengths, seen, excluded = [], 0, 0
+    for f in files:
+        for r in claude_code_turns(f, exclude)[0]:
+            if not r.steps:
+                continue
+            seen += 1
+            excluded += r.run in exclude
+            if r.success:
+                lengths.append(len(r.steps))
+    listing = "\n".join(f"{f.name}\t{f.stat().st_size}" for f in files)  # names and sizes only, never content
+    source = {"kind": "claude-code", "sha256": hashlib.sha256(listing.encode()).hexdigest(), "runs_seen": seen, "excluded": excluded}
+    return lengths, source
+
+
+def calibrate(source, *, project="default", alpha=0.05, home=None):
+    """Set a project's stop line from past runs and save it. Returns the calibration record.
+
+    `source`: a runs file (common format) or a Claude Code project folder. The record holds counts and a
+    fingerprint only, never text from the source (spec FR-007).
+    """
+    if not records.valid_project(project):
+        raise ValueError(f"project names may use letters, digits, '.', '_' and '-' (got {project!r})")
+    h = records.home(home)
+    src = Path(source).expanduser()
+    if not src.exists():
+        raise FileNotFoundError(f"no such file or folder: {src}")
+    exclude = records.read_exclude(h)
+    lengths, src_info = _from_claude_code(src, exclude) if src.is_dir() else _from_runs_file(src, exclude)
+    line = threshold(lengths, alpha)
+    rec = {
+        "v": 1, "project": project, "method": "steps", "alpha": alpha,
+        "n": len(lengths), "k": rank(len(lengths), alpha),
+        "stop_line": None if line == math.inf else int(line), "watch_only": line == math.inf,
+        "source": src_info, "created": date.today().isoformat(), "version": __version__,
+    }
+    p = path(project, h)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(json.dumps(rec, indent=1) + "\n")
+    return rec

loopbrake/cli.py

@@ -0,0 +1,111 @@
+"""The `loopbrake` command. Contract: specs/003-core-package/contracts/cli.md."""
+import argparse
+import os
+import sys
+
+from loopbrake import __version__, calibration, records
+from loopbrake.brake import replay
+from loopbrake.traces import read_runs
+
+
+def _calibrate(args):
+    rec = calibration.calibrate(args.source, project=args.project, alpha=args.alpha)
+    if rec["watch_only"]:
+        more = calibration.runs_needed(args.alpha) - rec["n"]
+        print(f"watch-only: {rec['n']} successful runs found; need {more} more for α {args.alpha:.0%}")
+    else:
+        print(f"stop line: {rec['stop_line']} steps (from {rec['n']} successful runs, k = {rec['k']}, α {args.alpha:.0%})")
+    print(f"saved: {calibration.path(args.project, records.home())}")
+    return 0
+
+
+def _status(args):
+    h = records.home()
+    projects = [args.project] if args.project else sorted(p.stem for p in (h / "calibration").glob("*.json")) or ["default"]
+    for project in projects:
+        rec = calibration.load(project, h)
+        if rec is None:
+            line = "no calibration (watch-only)"
+        elif rec["watch_only"]:
+            line = f"watch-only (only {rec['n']} successful runs)"
+        else:
+            line = f"stop line: {rec['stop_line']} steps (from {rec['n']} successful runs, α {rec['alpha']:.0%}, {rec['source']['kind']}, {rec['created']})"
+        st = records.status(h, project)
+        print(f"project {project}: {line}")
+        print(f"  runs watched: {st['watched']} (of {st['runs']} recorded)")
+        print(f"  runs stopped: {st['stopped']}")
+        print(f"  mistaken stops: {st['mistaken']} of an allowance of {st['allowance']:.1f}")
+    return 0
+
+
+def _feedback(args):
+    verdict = "mistaken_stop" if args.mistaken else "exclude"
+    try:
+        records.add_feedback(records.home(), args.run, verdict)
+    except LookupError as e:
+        print(f"loopbrake: {e}", file=sys.stderr)
+        return 1
+    print(f"recorded: {args.run} {'marked as a mistaken stop' if args.mistaken else 'left out of future calibration'}")
+    return 0
+
+
+def _replay(args):
+    if args.stop_line is not None:
+        cal = {"stop_line": args.stop_line, "watch_only": False}
+    else:
+        cal = calibration.load(args.project, records.home())
+        if cal is None or cal["watch_only"]:
+            print(f"loopbrake: project {args.project} has no stop line yet; calibrate it first", file=sys.stderr)
+            return 2
+    runs, _ = read_runs(args.runs_file)
+    stopped_ok = stopped_failed = 0
+    for r in runs:
+        if not r.steps:
+            continue
+        step = replay(r, cal)
+        if step is not None:
+            stopped_ok += r.success
+            stopped_failed += not r.success
+        print(f"{r.run}\t{'-' if step is None else f'stop at {step}'}\t{'success' if r.success else 'failed'}")
+    print(f"runs {sum(1 for r in runs if r.steps)}, stopped {stopped_ok + stopped_failed} ({stopped_ok} successful, {stopped_failed} failed)")
+    return 0
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="loopbrake", description="Stops stuck AI agent runs, with a guaranteed limit on stopping good ones.")
+    ap.add_argument("--version", action="store_true", help="print the version")
+    sub = ap.add_subparsers(dest="command")
+    c = sub.add_parser("calibrate", help="set a stop line from past runs")
+    c.add_argument("source", help="a runs file, or a Claude Code project folder")
+    c.add_argument("--project", default="default")
+    c.add_argument("--alpha", type=float, default=0.05, help="highest share of good runs you accept stopping (default 0.05)")
+    s = sub.add_parser("status", help="stop line, runs watched and stopped, mistaken stops")
+    s.add_argument("--project")
+    f = sub.add_parser("feedback", help="mark a stop as a mistake, or leave a run out of calibration")
+    f.add_argument("run")
+    g = f.add_mutually_exclusive_group(required=True)
+    g.add_argument("--mistaken", action="store_true")
+    g.add_argument("--exclude", action="store_true")
+    r = sub.add_parser("replay", help="show where recorded runs would stop (writes nothing)")
+    r.add_argument("runs_file")
+    g2 = r.add_mutually_exclusive_group(required=True)
+    g2.add_argument("--project")
+    g2.add_argument("--stop-line", type=int)
+    args = ap.parse_args(argv)
+    if args.version:
+        print(f"loopbrake {__version__}")
+        return 0
+    if not args.command:
+        ap.print_help()
+        return 0
+    try:
+        return {"calibrate": _calibrate, "status": _status, "feedback": _feedback, "replay": _replay}[args.command](args)
+    except (OSError, ValueError, KeyError) as e:
+        if os.environ.get("LOOPBRAKE_DEBUG") == "1":
+            raise
+        print(f"loopbrake: {e}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

loopbrake/conformal.py

@@ -0,0 +1,21 @@
+"""The stop-line rule (constitution Principle I).
+
+Given the scores of n past successful runs, pick the stop line so that a new successful run
+from the same agent and task mix goes over it with probability at most alpha.
+"""
+import math
+from fractions import Fraction
+
+
+def rank(n, alpha):
+    """Which calibration score becomes the stop line: the k-th smallest, k = ceil((n + 1)(1 - alpha)).
+
+    Exact fractions, so rounding can never change k.
+    """
+    return math.ceil((n + 1) * (1 - Fraction(str(alpha))))
+
+
+def threshold(run_scores, alpha):
+    """The stop line. math.inf when there are too few runs, so nothing is ever stopped."""
+    k = rank(len(run_scores), alpha)
+    return math.inf if k > len(run_scores) else sorted(run_scores)[k - 1]

loopbrake/records.py

@@ -0,0 +1,103 @@
+"""Local records: where LoopBrake keeps run records and the exclude list, and how status is read back.
+
+Format: specs/003-core-package/contracts/records.md. Nothing here touches the network (Principle VI).
+"""
+import json
+import os
+import re
+import warnings
+from datetime import datetime, timezone
+from pathlib import Path
+
+_PROJECT = re.compile(r"[A-Za-z0-9._-]{1,64}")
+VERDICTS = ("mistaken_stop", "exclude")
+
+
+def home(path=None):
+    """The LoopBrake folder: `path`, else $LOOPBRAKE_HOME, else ~/.loopbrake."""
+    return Path(path or os.environ.get("LOOPBRAKE_HOME") or Path.home() / ".loopbrake")
+
+
+def valid_project(name):
+    """Project names become file names, so only plain characters are allowed."""
+    return isinstance(name, str) and bool(_PROJECT.fullmatch(name)) and name not in (".", "..")
+
+
+def _now():
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+class RunWriter:
+    """Appends one event per line, readable only by the owner. If a write fails, recording turns off
+    for this writer; it never raises, so it can't hurt the agent being watched (spec FR-005)."""
+
+    def __init__(self, path):
+        self.path, self.on = Path(path), True
+
+    def write(self, event):
+        if not self.on:
+            return
+        line = (json.dumps({"v": 1, "ts": _now()} | event, ensure_ascii=False) + "\n").encode()
+        try:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            fd = os.open(self.path, os.O_WRONLY | os.O_APPEND | os.O_CREAT, 0o600)
+            try:
+                os.write(fd, line)  # one write per line, so parallel runs don't interleave
+            finally:
+                os.close(fd)
+        except OSError as e:
+            self.on = False
+            warnings.warn(f"loopbrake: can't write run records ({e}); recording is off for this run", RuntimeWarning, stacklevel=3)
+
+
+def _files(h):
+    return sorted((h / "runs").glob("*.jsonl")) if (h / "runs").exists() else []
+
+
+def read_events(h):
+    for path in _files(h):
+        for line in path.read_text(encoding="utf-8").splitlines():
+            try:
+                yield json.loads(line) | {"_file": path}
+            except json.JSONDecodeError:
+                continue
+
+
+def status(h, project=None):
+    """Runs, runs watched with a stop line, stops, stops marked mistaken, and the allowance (α × watched)."""
+    events = list(read_events(h))
+    starts = {e["run"]: e for e in events if e.get("event") == "run_start" and (project is None or e.get("project") == project)}
+    watched = {r: e for r, e in starts.items() if not (e.get("calibration") or {}).get("watch_only", True)}
+    stopped = {e["run"] for e in events if e.get("event") == "stop" and e.get("run") in starts}
+    mistaken = {e["run"] for e in events if e.get("event") == "feedback" and e.get("verdict") == "mistaken_stop" and e.get("run") in starts}
+    return {
+        "runs": len(starts),
+        "watched": len(watched),
+        "stopped": len(stopped),
+        "mistaken": len(mistaken),
+        "allowance": sum(e["calibration"].get("alpha", 0) for e in watched.values()),
+    }
+
+
+def add_feedback(h, run, verdict):
+    """Record that a stop was a mistake, or that a run should be left out of future calibration."""
+    if verdict not in VERDICTS:
+        raise ValueError(f"verdict must be one of {VERDICTS}")
+    start = next((e for e in read_events(h) if e.get("event") == "run_start" and e.get("run") == run), None)
+    if start is None:
+        raise LookupError(f"no run {run!r} in {h / 'runs'}")
+    RunWriter(start["_file"]).write({"event": "feedback", "session": start.get("session"), "run": run, "verdict": verdict})
+    if verdict == "exclude":
+        add_exclude(h, run)
+
+
+def read_exclude(h):
+    path = h / "exclude.txt"
+    return set(path.read_text().split()) if path.exists() else set()
+
+
+def add_exclude(h, run_id):
+    if run_id not in read_exclude(h):
+        h.mkdir(parents=True, exist_ok=True)
+        with open(h / "exclude.txt", "a", encoding="utf-8") as f:
+            f.write(run_id + "\n")

loopbrake/signals.py

@@ -0,0 +1,226 @@
+"""Stuck scores. A method turns a run's steps into one (score, reason) pair per step.
+
+Rules (constitution Principle II): a scorer looks only at the steps it is given, always gives
+the same output for the same input, and keeps nothing between calls.
+"""
+import re
+from collections import defaultdict
+from functools import partial
+from typing import NamedTuple
+
+
+class Step(NamedTuple):
+    action: str  # what the agent did, e.g. 'bash {"command": "ls"}'
+    observation: str  # what came back; may be empty
+    error: bool | None  # True/False when the source says so, None when unknown
+    tokens: int  # tokens billed for the model call that produced this step
+
+
+def _short(text, n=80):
+    text = " ".join(text.split())
+    return text if len(text) <= n else text[: n - 1] + "…"
+
+
+# ---------- simple methods (research R5) ----------
+
+
+def _fixed(steps):
+    """The original liveness.py rule: stop on the 3rd identical action, or at step 21."""
+    seen = defaultdict(list)
+    out = []
+    for t, s in enumerate(steps, 1):
+        seen[s.action].append(t)
+        count = len(seen[s.action])
+        if t > 20:
+            reason = "step limit of 20 reached"
+        elif count >= 3:
+            reason = f"same action seen {count} times (steps {', '.join(map(str, seen[s.action][-3:]))})"
+        else:
+            reason = ""
+        out.append((max(count / 3, t / 21), reason))
+    return out
+
+
+def _exact(steps):
+    """Most times any single action has been repeated so far."""
+    seen = defaultdict(int)
+    top, top_action, out = 0, "", []
+    for s in steps:
+        seen[s.action] += 1
+        if seen[s.action] > top:
+            top, top_action = seen[s.action], s.action
+        out.append((top, f"same action {top} times: {_short(top_action)}"))
+    return out
+
+
+def _steps(steps):
+    """How long the run has gone on (FailFast's "Duration" control)."""
+    return [(t, f"step {t}") for t in range(1, len(steps) + 1)]
+
+
+_BASELINE_SCORERS = {"fixed": _fixed, "exact": _exact, "steps": _steps}
+
+
+# ---------- stuck signals (research R6): each gives a value from 0 to 1 per step ----------
+
+WINDOW = 10  # a repeat is checked against this many previous actions
+RECENT = 5  # reasons describe this many latest steps
+_WORD = re.compile(r"[a-z0-9_]+")
+_DIGITS = re.compile(r"\d+")
+_ERROR_WORDS = re.compile(r"error|exception|traceback|not found|no such file", re.IGNORECASE)
+
+
+def _norm(line):
+    """Collapse spaces and turn every number into 0, so timestamps and counters don't look new."""
+    return _DIGITS.sub("0", " ".join(line.split()))
+
+
+def _fuzzy(steps):
+    """How closely this action repeats one of the previous 10: overlap of their word sets (Jaccard).
+
+    Digits are kept, so paging through a file (lines 100-200, then 200-300) is not a repeat.
+    """
+    words = [set(_WORD.findall(s.action.lower())) for s in steps]
+    out = []
+    for i, w in enumerate(words):
+        best, where = 0.0, None
+        for j in range(max(0, i - WINDOW), i):
+            union = w | words[j]
+            sim = len(w & words[j]) / len(union) if union else 0.0
+            if sim > 0 and sim >= best:  # on a tie, point at the latest step
+                best, where = sim, j
+        detail = "" if where is None else f"{'same command as' if best == 1 else 'similar to'} step {where + 1}"
+        out.append((best, detail))
+    return out
+
+
+def _stale(steps):
+    """Share of this step's output lines the run has already seen. Empty output scores 0:
+    many useful actions (like editing a file) print nothing."""
+    seen, out = set(), []
+    for s in steps:
+        lines = [x for x in map(_norm, s.observation.splitlines()) if x]
+        if not lines:
+            out.append((0.0, ""))
+            continue
+        new = sum(1 for x in lines if x not in seen)
+        seen.update(lines)
+        out.append((1 - new / len(lines), f"{new} of {len(lines)} output lines new"))
+    return out
+
+
+def _errors(steps):
+    """1 when this step fails with an error the run has already hit (same last line, numbers masked)."""
+    first, out = {}, []
+    for t, s in enumerate(steps, 1):
+        last = next((x for x in reversed(s.observation.splitlines()) if x.strip()), "")
+        failed = s.error if s.error is not None else bool(_ERROR_WORDS.search(last))
+        if not failed:
+            out.append((0.0, ""))
+            continue
+        sig = _norm(last)[:200]
+        if sig in first:
+            out.append((1.0, f"as step {first[sig]}: {_short(sig, 60)}"))
+        else:
+            first[sig] = t
+            out.append((0.0, ""))
+    return out
+
+
+_SIGNAL_FNS = {"fuzzy": _fuzzy, "stale": _stale, "errors": _errors}
+_LABELS = {"fuzzy": "repeating", "stale": "nothing new", "errors": "same error again"}
+_ALL = ("fuzzy", "stale", "errors")
+_PARTS = {"fuzzy": ("fuzzy",), "stale": ("stale",), "errors": ("errors",), "mean": _ALL, "max": _ALL, "loop": ("fuzzy", "stale")}
+
+
+def _combine(name, vals):
+    if name == "mean":
+        return sum(vals.values()) / len(vals)
+    if name == "max":
+        return max(vals.values())
+    if name == "loop":  # repeating AND learning nothing
+        return vals["fuzzy"] * vals["stale"]
+    return vals[name]
+
+
+def _reason(per, parts, i):
+    lo = max(0, i - RECENT + 1)
+    bits = []
+    for p in parts:
+        hits = [j for j in range(lo, i + 1) if per[p][j][0] >= 0.5]
+        if hits:
+            bits.append(f"{_LABELS[p]} in {len(hits)} of last {i - lo + 1} steps ({per[p][hits[-1]][1]})")
+    return "; ".join(bits)
+
+
+def _signal_scorer(name, lam, steps):
+    """Running score S_t = lam * S_(t-1) + u_t: one odd step fades, steady stuckness adds up."""
+    # ponytail: recomputes every signal from all steps on each call, so a live run costs O(t^2) overall.
+    # Fine for the 250-step runs seen here; Phase 2's Brake can keep running state instead, with the
+    # "never looks ahead" test checking both give the same scores.
+    parts = _PARTS[name]
+    per = {p: _SIGNAL_FNS[p](steps) for p in parts}
+    out, score = [], 0.0
+    for i in range(len(steps)):
+        score = lam * score + _combine(name, {p: per[p][i][0] for p in parts})
+        out.append((score, _reason(per, parts, i)))
+    return out
+
+
+BASELINES = tuple(_BASELINE_SCORERS)
+SIGNALS = tuple(_PARTS)
+METHODS = BASELINES + SIGNALS
+
+
+def method(name, lam=None):
+    """The scorer for a method: scorer(steps) -> [(score, reason), ...], one per step."""
+    if name in BASELINES:
+        if lam is not None:
+            raise ValueError(f"{name} takes no lam")
+        return _BASELINE_SCORERS[name]
+    if name in SIGNALS:
+        if lam is None:
+            raise ValueError(f"{name} needs lam")
+        return partial(_signal_scorer, name, float(lam))
+    raise ValueError(f"unknown method {name!r}")
+
+
+# ---------- judged scores (feature 002, research R6) ----------
+# A judge says how likely each step was to make progress (p, 0 to 1). These scorers turn those
+# answers into a stuck score. They stay pure: the same steps and answers always give the same scores.
+
+JUDGED = ("judge", "judge_steps", "judge_max")
+
+
+def _judged_scorer(name, lam, steps, progress, kinds=None):
+    """progress[i] is P(progress) for step i, or None for "no opinion", which leaves the score as it was.
+    kinds[i] is an optional (kind, p) pair; it only feeds the reason text."""
+    cheap = [max(v for v, _ in vals) for vals in zip(*(_SIGNAL_FNS[s](steps) for s in _ALL))] if name == "judge_max" else None
+    out, score = [], 0.0
+    for i, p in enumerate(progress):
+        if p is not None:
+            if name == "judge":
+                u = 1 - p
+            elif name == "judge_steps":
+                u = (1 + (1 - p)) / 2  # every step costs some time; an unproductive one costs more
+            else:
+                u = max(1 - p, cheap[i])
+            score = lam * score + u
+        lo = max(0, i - RECENT + 1)
+        stuck = sum(1 for q in progress[lo : i + 1] if q is not None and q < 0.5)
+        reason = ""
+        if stuck:
+            reason = f"judge: no progress in {stuck} of last {i - lo + 1} steps"
+            if kinds and kinds[i]:
+                reason += f" ({kinds[i][0]}, {kinds[i][1]:.2f})"
+        out.append((score, reason))
+    return out
+
+
+def judged(name, lam):
+    """Scorer for a judged method: scorer(steps, progress, kinds=None) -> [(score, reason), ...]."""
+    if name not in JUDGED:
+        raise ValueError(f"unknown judged method {name!r}")
+    if lam is None:
+        raise ValueError(f"{name} needs lam")
+    return partial(_judged_scorer, name, float(lam))

loopbrake/traces.py

@@ -0,0 +1,186 @@
+"""Read and write runs. A run is one agent attempt at one task, as a list of steps.
+
+File format: specs/001-offline-eval/contracts/normalized-runs.md (JSON Lines, one run per line).
+"""
+import json
+from collections import Counter
+from pathlib import Path
+from typing import NamedTuple
+
+from loopbrake.signals import Step
+
+
+class Run(NamedTuple):
+    group: str
+    dataset: str
+    task: str
+    run: str
+    success: bool
+    exit: str | None
+    tokens_measured: bool
+    steps: tuple  # of Step, in order, never empty
+
+
+def write_runs(path, runs):
+    with open(path, "w", encoding="utf-8") as f:
+        for r in runs:
+            d = r._asdict()
+            d["steps"] = [s._asdict() for s in r.steps]
+            f.write(json.dumps(d, ensure_ascii=False) + "\n")
+
+
+def read_runs(path):
+    """Returns (runs, skipped). A bad line is skipped and counted by reason; it never raises."""
+    runs, skipped = [], Counter()
+    with open(path, encoding="utf-8") as f:
+        for line in f:
+            if not line.strip():
+                continue
+            try:
+                d = json.loads(line)
+            except json.JSONDecodeError:
+                skipped["bad json"] += 1
+                continue
+            problem = _problem(d)
+            if problem:
+                skipped[problem] += 1
+                continue
+            steps = tuple(Step(s["action"], s["observation"], s["error"], s["tokens"]) for s in d["steps"])
+            runs.append(Run(d["group"], d["dataset"], d["task"], d["run"], d["success"], d["exit"], d["tokens_measured"], steps))
+    return runs, skipped
+
+
+def _problem(d):
+    if not isinstance(d, dict) or not all(isinstance(d.get(k), str) for k in ("group", "dataset", "task", "run")):
+        return "bad field"
+    if not isinstance(d.get("success"), bool) or not isinstance(d.get("tokens_measured"), bool):
+        return "bad field"
+    if d.get("exit") is not None and not isinstance(d["exit"], str):
+        return "bad field"
+    steps = d.get("steps")
+    if not isinstance(steps, list) or not steps:
+        return "no steps"
+    for s in steps:
+        if not isinstance(s, dict) or not isinstance(s.get("observation"), str):
+            return "bad field"
+        if not isinstance(s.get("action"), str) or not s["action"]:
+            return "empty action"
+        tokens = s.get("tokens")
+        if not isinstance(tokens, int) or isinstance(tokens, bool) or tokens < 0:
+            return "bad tokens"
+        if "error" not in s or (s["error"] is not None and not isinstance(s["error"], bool)):
+            return "bad error flag"  # isinstance, because 1 == True would sneak past an `in` check
+    return None
+
+
+# ---------- Claude Code session transcripts (research R10) ----------
+# The format is internal to Claude Code and can change between releases, so this is the only
+# function that reads it, and tests/fixtures/claude_code_session.jsonl pins what it expects.
+
+INTERRUPTED = "[Request interrupted by user"
+
+
+def _text(content):
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        return "\n".join(b.get("text", "") for b in content if isinstance(b, dict) and b.get("type") == "text")
+    return ""
+
+
+def _usage_tokens(usage):
+    """Every token the call read or wrote, cached or not: what the turn really consumed."""
+    keys = ("input_tokens", "cache_creation_input_tokens", "cache_read_input_tokens", "output_tokens")
+    return sum(usage.get(k) or 0 for k in keys) if isinstance(usage, dict) else 0
+
+
+class _Turn:
+    def __init__(self, turn_id):
+        self.id, self.steps, self.by_call = turn_id, [], {}
+        self.interrupted, self.pending = False, 0
+        self.msg, self.msg_tokens, self.msg_charged = None, 0, True
+
+    def add_tokens(self, n):  # to the previous step, or held for the first one
+        if self.steps:
+            self.steps[-1]["tokens"] += n
+        else:
+            self.pending += n
+
+    def close_message(self):  # a response that called no tool: its tokens go to the step before it
+        if self.msg is not None and not self.msg_charged:
+            self.add_tokens(self.msg_tokens)
+        self.msg_charged = True
+
+    def run(self, group, exclude):
+        self.close_message()
+        steps = tuple(Step(s["action"], s["observation"], s["error"], s["tokens"]) for s in self.steps)
+        exit = "interrupted" if self.interrupted else None
+        return Run(group, "claude-code-local", self.id, self.id, not self.interrupted and self.id not in exclude, exit, True, steps)
+
+
+def claude_code_turns(transcript, exclude=()):
+    """Split one Claude Code session transcript into turns, one Run per user prompt.
+
+    Returns (runs, skipped). A turn succeeds when it was not interrupted and is not in `exclude`
+    (turn ids: the uuid of the prompt record). The run's group is the project folder name; callers
+    rename it before anything leaves the machine (constitution Principle VI).
+    """
+    group = Path(transcript).parent.name
+    runs, skipped, seen_msgs = [], Counter(), set()
+    turn = None
+    with open(transcript, encoding="utf-8") as f:
+        for line in f:
+            try:
+                rec = json.loads(line)
+            except json.JSONDecodeError:
+                skipped["bad json"] += 1
+                continue
+            if rec.get("isSidechain"):
+                skipped["sidechain"] += 1
+                continue
+            kind, msg = rec.get("type"), rec.get("message")
+            if kind not in ("user", "assistant") or not isinstance(msg, dict):
+                skipped["not a message"] += 1
+                continue
+            content = msg.get("content")
+            if kind == "user":
+                if rec.get("isMeta"):
+                    continue
+                results = [b for b in content if isinstance(b, dict) and b.get("type") == "tool_result"] if isinstance(content, list) else []
+                if results:
+                    for b in results:
+                        step = turn.by_call.get(b.get("tool_use_id")) if turn else None
+                        if step is not None:
+                            step["observation"] = _text(b.get("content"))
+                            step["error"] = bool(b.get("is_error", False))
+                    continue
+                text = _text(content)
+                if text.startswith(INTERRUPTED):
+                    if turn:
+                        turn.interrupted = True
+                    continue
+                if text.startswith("<local-command"):
+                    continue
+                if turn:
+                    runs.append(turn.run(group, exclude))
+                turn = _Turn(rec.get("uuid") or f"turn-{len(runs) + 1}")
+                continue
+            if turn is None:
+                continue  # assistant output before any prompt
+            mid = msg.get("id")
+            if mid != turn.msg:
+                turn.close_message()
+                turn.msg, turn.msg_charged = mid, False
+                turn.msg_tokens = 0 if mid in seen_msgs else _usage_tokens(msg.get("usage"))
+                seen_msgs.add(mid)  # one response is split across records that repeat its usage
+            for b in content if isinstance(content, list) else []:
+                if isinstance(b, dict) and b.get("type") == "tool_use":
+                    tokens = 0 if turn.msg_charged else turn.msg_tokens + turn.pending
+                    turn.msg_charged, turn.pending = True, 0
+                    step = {"action": f"{b.get('name')} {json.dumps(b.get('input') or {}, sort_keys=True, ensure_ascii=False)}",
+                            "observation": "", "error": None, "tokens": tokens}
+                    turn.steps.append(step)
+                    turn.by_call[b.get("id")] = step
+    if turn:
+        runs.append(turn.run(group, exclude))
+    return runs, skipped

loopbrake-0.1.0.dist-info/METADATA

@@ -0,0 +1,255 @@
+Metadata-Version: 2.5
+Name: loopbrake
+Version: 0.1.0
+Summary: Stops stuck AI agent runs, with a guaranteed limit on stopping good ones.
+Project-URL: Homepage, https://github.com/SahilSelokar/LoopBrake
+Project-URL: Source, https://github.com/SahilSelokar/LoopBrake
+Project-URL: Results, https://github.com/SahilSelokar/LoopBrake/tree/main/eval/results
+Author: Sahil Selokar
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent loops,ai agents,claude code,conformal prediction,llm,stop controller
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Provides-Extra: agent-sdk
+Requires-Dist: claude-agent-sdk; extra == 'agent-sdk'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# LoopBrake
+
+**Brakes for stuck AI agents.**
+
+Stop agent runs that are going in circles, with a guaranteed limit on how often a good run gets stopped.
+
+[![Status](https://img.shields.io/badge/status-research%20phase-orange)](#status)
+[![Python](https://img.shields.io/badge/python-3.11%2B-3776AB)](pyproject.toml)
+[![Dependencies](https://img.shields.io/badge/runtime%20dependencies-0-brightgreen)](pyproject.toml)
+[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+</div>
+
+---
+
+## The problem
+
+AI agents get stuck. They run the same command again and again, re-read the same file, or hit the
+same error, and they keep spending tokens until a step or budget limit finally stops them.
+
+The usual fixes are blunt: a fixed step limit, or a rule like "stop after the same action 3 times".
+Set them tight and you kill runs that would have succeeded. Set them loose and you pay for every loop.
+
+## The idea
+
+LoopBrake watches a run one step at a time and gives each step a **stuck score**. When the score
+crosses a **stop line**, it stops the run and says why.
+
+The stop line is not guessed. It is set from **your own past successful runs**, so that at most a
+chosen share of good runs, for example 5 in 100, would ever cross it. That is a statistical
+guarantee (split-conformal calibration), not a tuned target.
+
+**In v1 the stuck score is simply how long the run has gone on.** Two experiments (below) tested
+smarter scores, and neither beat it on agents they were not tuned on. The stuck signals (repeats,
+nothing new, same error again) still run, but only to explain why a stopped run looked stuck.
+
+```mermaid
+flowchart LR
+    A[Agent takes a step] --> B[Stuck score]
+    B --> C{Above the stop line?}
+    C -- no --> A
+    C -- yes --> D[Stop the run and say why]
+    E[(Your past successful runs)] -. set the stop line .-> C
+```
+
+## What a stop looks like
+
+A real run from the public SWE-bench data (GPT-5-mini), replayed through LoopBrake. The agent kept
+searching the same files for a function and found nothing new:
+
+```text
+swe-gpt5mini · matplotlib__matplotlib-25775 · stopped at step 27 of 72 · saved 2,023,115 tokens (84%)
+Reason: repeating in 5 of last 5 steps (similar to step 19); nothing new in 2 of last 5 steps (0 of 21 output lines new)
+
+  23  sed -n '760,1080p' lib/matplotlib/backend_bases.py
+  24  grep -n "def set_antialiased" -n lib/matplotlib/backend_bases.py || true
+  25  sed -n '892,932p' lib/matplotlib/backend_bases.py
+  26  sed -n '1,220p' lib/matplotlib/patches.py
+  27  grep -n "set_antialiased" -n lib -R || true
+```
+
+More in [eval/results/kill-stories.md](eval/results/kill-stories.md).
+
+## Use it
+
+**Install.** `pip install loopbrake`, or `uv add loopbrake`. Until the first PyPI release, use
+`pip install git+https://github.com/SahilSelokar/LoopBrake`. No other packages are needed.
+
+**1. Set your stop line from your own past runs.** It needs at least 19 successful runs (at α 5%);
+with fewer, LoopBrake only watches.
+
+```bash
+loopbrake calibrate ~/.claude/projects/<your-project>/ --project my-agent   # your Claude Code history
+loopbrake calibrate my_runs.jsonl --project my-agent                         # or recorded runs
+```
+
+**2. Add it to your agent loop.**
+
+```python
+import loopbrake
+
+with loopbrake.start(project="my-agent") as brake:
+    for action, result in my_agent_steps():          # your loop
+        decision = brake.step(action, result)
+        if decision.stop:
+            print(decision.reason); break
+```
+
+**3. See how it's doing.**
+
+```bash
+loopbrake status --project my-agent        # runs watched, stops, and stops you marked as mistakes
+loopbrake feedback <run-id> --mistaken     # tell LoopBrake a stop was wrong
+```
+
+**Claude's agent toolkit:** `pip install "loopbrake[agent-sdk]"`, then
+`ClaudeAgentOptions(hooks=loopbrake.agent_sdk.hooks(project="my-agent"))`.
+
+Everything stays on your machine, in `~/.loopbrake`. LoopBrake never uses the network. If something
+inside it fails, it switches to watching only. It never crashes or stops your agent because of its
+own problem.
+
+## Phase 1 results
+
+Before building the product, we tested the idea offline. We replayed **2,979 recorded runs** from
+six agent groups, on coding tasks
+([SWE-bench Verified](https://github.com/SWE-bench/experiments)) and customer-service tasks
+([τ-bench](https://github.com/sierra-research/tau-bench)).
+
+| Finding | Result |
+|---|---|
+| The guarantee held: good runs stopped by the chosen method, on every test group | **at most 4.9%** (limit 5%) |
+| The naive rule "stop at 20 steps or 3 repeats" stops good runs | **99.3%** (Devstral), **29.1%** (GPT-5-mini) |
+| Tokens saved by a calibrated step limit (GPT-5-mini, 100 past runs) | **11.2%** |
+| Tokens saved by the stuck signals (same setting) | **12.9%** |
+| Extra saving from stuck signals over the step limit, with 95% interval | SWE-bench **+1.5%** [−9.7%, +13.2%]<br>τ-bench **+0.9%** [−3.1%, +5.0%] |
+
+**Verdict: NO-GO.** The cheap stuck signals do not clearly beat a calibrated step limit. Following
+the plan set in advance, a second experiment tested a progress judge (below).
+For comparison, [FailFast](https://arxiv.org/abs/2608.03222), a trained monitor, reports 14.6–20.4%
+saved at 5% of good runs stopped. Its threshold was set on the same data it reports on, though, so
+that 5% is a target, not a guarantee.
+
+Full report: [eval/results/results.md](eval/results/results.md)
+
+## Progress judge: also NO-GO
+
+Counting repeats is not the same as understanding a step, so the second experiment asked a fast
+hosted decision model, [Jev](https://docs.typesafe.ai) (`jev-1.13.0`), about every step: *did this
+move the agent closer to finishing?* and *what kind of step was it?* Savings are counted **net**:
+every token the judge reads is subtracted. The method was chosen on one agent and committed
+(`0827ece`) before any other agent was judged.
+
+| Dataset | Extra net saving over the step limit, with 95% interval |
+|---|---|
+| SWE-bench (GPT-5-mini) | **−6.3%** [−18.9%, +1.9%] |
+| τ-bench (4 groups) | **−4.2%** [−8.2%, −1.5%] |
+
+What we learned:
+
+- **A threshold tuned on one agent did not travel.** The chosen method asked the judge only when the
+  cheap score passed a level set on Devstral's long runs. On the other agents that level was almost
+  never reached (0–0.3% of steps), so the method rarely stopped anything.
+- **A judge on every step is expensive.** On short customer-service tasks it used about as many
+  tokens as the agent itself.
+- **Even ignoring its cost, the judge did not spot stuck runs better than counting steps**: for
+  example 7.3% vs 9.3% of tokens saved on GPT-5-mini.
+- The guarantee held on every group. The whole experiment took 73,812 judgments, for about $3.91.
+
+Full report: [eval/results/judge/results.md](eval/results/judge/results.md)
+
+## How the results are kept honest
+
+- **Chosen in advance.** The method was picked using one agent's runs and committed *before* any
+  test runs were scored (commits `8b8eaf3` and, for the judge, `0827ece`).
+- **Mistakes stay visible.** The first results were committed exactly as they came out, including a
+  flaw in how runs were split (`e655b96`). The fix is a separate, documented commit (`76e8cdc`), with
+  before-and-after numbers in [CORRECTIONS.md](eval/results/CORRECTIONS.md).
+- **Tested on unseen runs.** The stop line is always checked on runs it was not set from.
+- **Reproducible.** Every number above comes from `eval/results/` and comes out identical on every run.
+
+## How the guarantee works
+
+1. Each step gets a stuck score. A run's score is the highest score it reaches.
+2. Take *n* past successful runs and sort their scores. The stop line is the *k*-th smallest score,
+   where *k* = ⌈(*n* + 1)(1 − α)⌉ and α is the share of good runs you accept losing (for example 5%).
+3. A new successful run then crosses the stop line with probability at most α.
+
+With α = 5%, LoopBrake needs at least 19 past successful runs. With fewer, it only watches and
+never stops anything.
+
+The guarantee holds when new runs look like the past ones (same agent, same kind of tasks), and when
+the past runs come from different tasks. We learned the second condition the hard way: see
+[CORRECTIONS.md](eval/results/CORRECTIONS.md).
+
+## Reproduce
+
+Requires [uv](https://docs.astral.sh/uv/) and Python 3.11+.
+
+```bash
+git clone https://github.com/SahilSelokar/LoopBrake && cd LoopBrake
+uv run pytest                        # the test suite
+uv run python eval/fetch.py          # one-time download, about 450 MB, into ~/.loopbrake/data
+uv run python eval/run.py --final    # about 1 minute; writes eval/results/
+```
+
+The progress judge needs a [Typesafe](https://typesafe.ai) API key in `TYPESAFE_API_KEY` (or in
+`~/.loopbrake/typesafe_key`). Judging every public step costs about $4:
+
+```bash
+uv run python eval/tasks.py                              # task texts for the judge
+uv run python eval/judge.py --group swe-devstral         # one group at a time; resumable
+uv run python eval/judge_eval.py --final                 # reads stored answers only; writes eval/results/judge/
+```
+
+## Repository layout
+
+```text
+src/loopbrake/   scoring core: stuck signals, stop-line rule, run readers (standard library only)
+eval/            the experiments: fetch.py downloads the data, run.py replays runs, judge.py asks the
+                 progress judge, judge_eval.py scores its answers; results/ holds the published numbers
+specs/           design: constitution, roadmap, and the spec, plan, research and tasks of each experiment
+tests/           tests, including a check of the guarantee on simulated data
+liveness.py      the original naive rule, kept as the baseline
+```
+
+## Roadmap
+
+| Phase | What | Status |
+|---|---|---|
+| 1 | **Experiment**: does it work on real runs? | Done: NO-GO for cheap signals |
+| 1b | **Progress judge**: a hosted decision model judges whether each step moved the run forward | Done: NO-GO |
+| 2 | **Python package**: `pip install loopbrake`; a stop line on run length, with a guarantee and a readable reason | Built (v0.1.0); first PyPI release pending |
+| 3 | **Claude Code plugin**: stop stuck sessions live, calibrated on your own history | Planned |
+| 4 | **Observability**: live dashboard, plus export to Datadog, Grafana and others via OpenTelemetry | Planned |
+| 5 | **Launch**: a demo agent, the public release and a video | Planned |
+
+The full plan is in [specs/roadmap.md](specs/roadmap.md).
+
+## Status
+
+v0.1.0 is built and tested. The first PyPI release comes once publishing is set up; until then,
+install from GitHub (see "Use it"). Its stop rule is a stop line on run length, set from your own past
+successful runs, with a guaranteed limit on stopping good runs.
+
+## License
+
+[MIT](LICENSE). One test fixture is a trimmed τ-bench run, used under τ-bench's own MIT license
+(see [tests/fixtures/NOTICE.md](tests/fixtures/NOTICE.md)).

loopbrake-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+loopbrake/__init__.py,sha256=z8u1dzoZoj7ga-0G6rQkU7SCdytA-7ZJYaH7lgM4Oug,308
+loopbrake/agent_sdk.py,sha256=P8MJHWh13fK_ollf1YmsdHG_T8wCssu4WcWJNvnExxI,3379
+loopbrake/brake.py,sha256=kdqqVmv0tAsakUOXMWnbc8C5_5vOgk28V08G9a4FkiI,5408
+loopbrake/calibration.py,sha256=yvnQvKX9eeZFbC_lSNmbMPFSoTTZdDIUC5rCBU0uReg,4244
+loopbrake/cli.py,sha256=JlsdMvzjjYw4BjQiQfxvu8NFcs8gEv2XbcKOpqmHUg8,4819
+loopbrake/conformal.py,sha256=DY-73iNiIVk-_XpQi-A3yDrxpZ_D8ce9_Iw8VT289eM,752
+loopbrake/records.py,sha256=RrNXQ3bO25D8ZiOjWIP2TSQ4aQCZbti-n01mZ4btNxs,4039
+loopbrake/signals.py,sha256=r7DFUUDUR_D-QQc5vk6F_jfBzvB5rXPMj_7vB8ie8vM,8519
+loopbrake/traces.py,sha256=bGGfrR9tPLpR0H86tDH2MdyUK2EJjV-3MyfCYqrQtgU,7837
+loopbrake-0.1.0.dist-info/METADATA,sha256=j_rQOUkizzgStVrU53o_LEqHncRYXLpy3egaTbzmxeE,11964
+loopbrake-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+loopbrake-0.1.0.dist-info/entry_points.txt,sha256=nHCcVuPCF8zXEf9raOwfRLiyqz7S_lp7qrdODRqDgFM,49
+loopbrake-0.1.0.dist-info/licenses/LICENSE,sha256=fkXmARFvnpYeFBsjGBm6VWDxGO0IiF0UuStAscn_U6s,1070
+loopbrake-0.1.0.dist-info/RECORD,,

loopbrake-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

loopbrake-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+loopbrake = loopbrake.cli:main

loopbrake-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sahil Selokar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.