agentboxx 0.2.1__py3-none-any.whl

agentbox/__init__.py

@@ -0,0 +1,5 @@
+from .recorder import Recorder
+from .signer import ChainWriter, load_or_create_key, verify_file, verify_log
+
+__all__ = ["Recorder", "ChainWriter", "load_or_create_key", "verify_file", "verify_log"]
+__version__ = "0.2.1"

agentbox/agent.py

@@ -0,0 +1,138 @@
+"""A minimal ReAct-style agent loop wired to the recorder.
+
+Loop: model proposes a command -> sandbox runs it -> recorder logs it ->
+the observation (plus any loop-detector hint) goes back to the model.
+"""
+import json
+
+SYSTEM_PROMPT = (
+    "You are a coding agent working in a sandbox with a bash tool. "
+    "Reply with ONLY one JSON object, no other text. "
+    'To run a command: {"thought": "why", "command": "bash command"}. '
+    'When the goal is done: {"thought": "why", "final": "short answer"}. '
+    "If you receive an [agentbox hint], change your approach."
+)
+
+
+class ScriptedModel:
+    """A fake model for demos and tests. Retries a failing command, then
+    changes approach once it receives an [agentbox hint]."""
+
+    def __init__(self):
+        self.plan = [
+            ("Create a small script.", "printf 'x = 0\\nprint(10 / x)\\n' > main.py"),
+            ("Run it.", "python3 main.py"),
+        ]
+        self.recovery = [
+            ("The hint is right: x = 0 causes the crash. Fix the value.", "sed -i 's/x = 0/x = 2/' main.py"),
+            ("Run it again.", "python3 main.py"),
+            ("DONE", None),
+        ]
+        self.i, self.recovering = 0, False
+
+    def next_action(self, messages):
+        if not self.recovering and "[agentbox hint]" in messages[-1]["content"]:
+            self.recovering, self.i = True, 0
+        steps = self.recovery if self.recovering else self.plan
+        thought, cmd = steps[min(self.i, len(steps) - 1)]
+        self.i += 1
+        if cmd is None:
+            return {"thought": "The script runs now.", "final": "Fixed the divide-by-zero; script prints 5.0."}
+        return {"thought": thought, "command": cmd}
+
+
+class AnthropicModel:
+    """Real model via the Anthropic API. Needs `pip install anthropic` and
+    the ANTHROPIC_API_KEY environment variable."""
+
+    def __init__(self, model="claude-sonnet-5-5"):
+        import anthropic
+        self.client, self.model = anthropic.Anthropic(), model
+
+    def next_action(self, messages):
+        r = self.client.messages.create(model=self.model, max_tokens=1000,
+                                        system=SYSTEM_PROMPT, messages=messages)
+        text = r.content[0].text.strip()
+        if text.startswith("```"):
+            text = text.strip("`").removeprefix("json").strip()
+        try:
+            return json.loads(text)
+        except json.JSONDecodeError:
+            return {"thought": "unparseable reply", "final": text[:500]}
+
+
+
+class GeminiModel:
+    """Real model via the Google Gemini REST API (stdlib only, no SDK needed).
+    Needs the GEMINI_API_KEY environment variable."""
+
+    def __init__(self, model="gemini-flash-lite-latest"):
+        import os
+        key = os.environ.get("GEMINI_API_KEY")
+        if not key:
+            raise RuntimeError("set the GEMINI_API_KEY environment variable")
+        self._model = model
+        self._url = (
+            f"https://generativelanguage.googleapis.com/v1beta/"
+            f"models/{model}:generateContent?key={key}"
+        )
+
+    def next_action(self, messages):
+        import urllib.request
+        contents = []
+        for m in messages:
+            role = "model" if m["role"] == "assistant" else "user"
+            contents.append({"role": role, "parts": [{"text": m["content"]}]})
+        body = json.dumps({
+            "system_instruction": {"parts": [{"text": SYSTEM_PROMPT}]},
+            "contents": contents,
+        }).encode("utf-8")
+        req = urllib.request.Request(
+            self._url, data=body,
+            headers={"Content-Type": "application/json"},
+        )
+        with urllib.request.urlopen(req, timeout=60) as resp:
+            data = json.loads(resp.read())
+        text = data["candidates"][0]["content"]["parts"][0]["text"].strip()
+        if text.startswith("```"):
+            text = text.strip("`").removeprefix("json").strip()
+        try:
+            return json.loads(text)
+        except json.JSONDecodeError:
+            return {"thought": "unparseable reply", "final": text[:500]}
+
+
+def _format_observation(obs: dict) -> str:
+    return (f"exit_code={obs['exit_code']}\n"
+            f"stdout:\n{obs['stdout']['text'][-1500:]}\n"
+            f"stderr:\n{obs['stderr']['text'][-1500:]}")
+
+
+def run_agent(goal, model, recorder, max_steps=15, verbose=True) -> dict:
+    messages = [{"role": "user", "content": f"Goal: {goal}"}]
+    reason, final = "max_steps", None
+    for _ in range(max_steps):
+        action = model.next_action(messages)
+        messages.append({"role": "assistant", "content": json.dumps(action)})
+        if action.get("final") is not None:
+            reason, final = "final_answer", action["final"]
+            break
+        cmd = action.get("command")
+        if not cmd:
+            messages.append({"role": "user", "content": "Reply with a command or a final answer."})
+            continue
+        result = recorder.run(cmd, thought=action.get("thought", ""))
+        obs, signals = result["observation"], result["signals"]
+        if verbose:
+            print(f"[{recorder.step_index}] {action.get('thought', '')}\n    $ {cmd}  -> exit {obs['exit_code']}")
+            for s in signals:
+                print(f"    !! {s['severity']}: {s['kind']}")
+        critical = [s for s in signals if s["severity"] == "critical"]
+        if critical:
+            reason = f"terminated: {critical[0]['kind']}"
+            break
+        text = _format_observation(obs)
+        if signals:
+            text += "\n\n[agentbox hint] " + " ".join(sorted({s["hint"] for s in signals}))
+        messages.append({"role": "user", "content": text})
+    return {"reason": reason, "final": final}

agentbox/cli.py

@@ -0,0 +1,252 @@
+"""Command-line interface: verify, report, list and demo."""
+import argparse
+import json
+import os
+import shutil
+import sys
+import tempfile
+from datetime import datetime
+from pathlib import Path
+
+from . import __version__
+from .signer import load_or_create_key, verify_log
+from .report import build_report_data, render_text, render_json, render_html
+
+EXIT_OK = 0
+EXIT_TAMPERED = 1
+EXIT_INCOMPLETE = 2
+EXIT_ERROR = 3          # missing, empty or unreadable input (not a verdict on the log)
+
+_RED, _YELLOW, _RESET = "\033[31m", "\033[33m", "\033[0m"
+
+
+class CliError(Exception):
+    """A problem with the input that should be shown as a message, not a traceback."""
+
+
+def _use_color(stream=None) -> bool:
+    """Color only on a terminal, and never when NO_COLOR is set (https://no-color.org)."""
+    stream = stream if stream is not None else sys.stdout
+    if os.environ.get("NO_COLOR"):
+        return False
+    if os.environ.get("TERM") == "dumb":
+        return False
+    isatty = getattr(stream, "isatty", None)
+    return bool(isatty and isatty())
+
+
+def _paint(text: str, color: str, enabled: bool) -> str:
+    return f"{color}{text}{_RESET}" if enabled else text
+
+
+def _check_readable(path) -> None:
+    p = Path(path)
+    if not p.exists():
+        raise CliError(f"file not found: {path}")
+    if p.is_dir():
+        raise CliError(f"{path} is a directory, not a log file")
+    try:
+        size = p.stat().st_size
+    except OSError as e:
+        raise CliError(f"cannot read {path}: {e.strerror or e}")
+    if size == 0:
+        raise CliError(f"log file is empty: {path}")
+
+
+def _run_verify(path, key=None):
+    """Return (problems, incomplete). Raises CliError for missing, empty or unreadable files."""
+    _check_readable(path)                      # before the key lookup, so a typo creates no key
+    key = key if key is not None else load_or_create_key()
+    try:
+        return verify_log(path, key)
+    except (OSError, UnicodeDecodeError) as e:
+        raise CliError(f"cannot read {path}: {getattr(e, 'strerror', None) or e}")
+    except (KeyError, TypeError, AttributeError):
+        return ["a record is malformed (not a valid agentbox record)"], []
+
+
+def _verify_and_print(path, key=None) -> int:
+    problems, incomplete = _run_verify(path, key)
+    if problems:
+        print("LOG HAS BEEN TAMPERED WITH OR IS CORRUPT:")
+        for p in problems:
+            print("  -", p)
+        return EXIT_TAMPERED
+    if incomplete:
+        print("INCOMPLETE LOG (chain and signatures are valid so far):")
+        for p in incomplete:
+            print("  -", p)
+        return EXIT_INCOMPLETE
+    print("OK: log is intact (chain and signatures valid).")
+    return EXIT_OK
+
+
+def cmd_verify(args) -> int:
+    return _verify_and_print(args.logfile)
+
+
+def _read_events(path) -> list:
+    _check_readable(path)
+    events = []
+    try:
+        with open(path, encoding="utf-8") as f:
+            for n, line in enumerate(f, 1):
+                if not line.strip():
+                    continue
+                try:
+                    ev = json.loads(line)["event"]
+                    ev["event_type"]
+                except (ValueError, KeyError, TypeError):
+                    raise CliError(f"{path}: line {n} is not a valid agentbox record")
+                events.append(ev)
+    except (OSError, UnicodeDecodeError) as e:
+        raise CliError(f"cannot read {path}: {getattr(e, 'strerror', None) or e}")
+    return events
+
+
+def cmd_report(args) -> int:
+    events = _read_events(args.logfile)
+    fmt = getattr(args, "format", "text") or "text"
+    out_path = getattr(args, "output", None)
+    try:
+        data = build_report_data(events)
+        if fmt == "json":
+            rendered = render_json(data)
+        elif fmt == "html":
+            rendered = render_html(data)
+        else:
+            color = _use_color(stream=sys.stdout if not out_path else None)
+            rendered = render_text(data, color=color)
+    except (KeyError, TypeError) as e:
+        raise CliError(f"{args.logfile}: a record is missing the field {e}")
+
+    if out_path and out_path != "-":
+        try:
+            Path(out_path).write_text(rendered, encoding="utf-8")
+        except OSError as e:
+            raise CliError(f"cannot write to {out_path}: {getattr(e, 'strerror', None) or e}")
+    else:
+        print(rendered, end="")
+    return EXIT_OK
+
+
+def _peek(path):
+    """Cheap, tolerant read for `list`: (session_id, start timestamp, step count)."""
+    session, started, steps = Path(path).stem, None, 0
+    with open(path, encoding="utf-8", errors="replace") as f:
+        for line in f:
+            try:
+                ev = json.loads(line)["event"]
+                etype = ev["event_type"]
+            except (ValueError, KeyError, TypeError):
+                continue
+            if started is None and isinstance(ev.get("ts"), (int, float)):
+                started = ev["ts"]
+            data = ev.get("data")
+            if etype == "session.start" and isinstance(data, dict):
+                session = str(data.get("session_id", session))
+            elif etype == "step":
+                steps += 1
+    return session, started, steps
+
+
+def cmd_list(args) -> int:
+    root = Path(args.directory)
+    if not root.is_dir():
+        raise CliError(f"directory not found: {args.directory}")
+    logs = sorted(root.glob("*.ndjson"))
+    if not logs:
+        print(f"No logs found in {args.directory}")
+        return EXIT_OK
+    key = load_or_create_key()
+    rows = []
+    for path in logs:
+        try:
+            session, started, steps = _peek(path)
+            problems, incomplete = _run_verify(path, key)
+            status = "TAMPERED" if problems else "INCOMPLETE" if incomplete else "OK"
+        except CliError:
+            session, started, steps = path.stem, None, 0
+            status = "EMPTY" if path.stat().st_size == 0 else "UNREADABLE"
+        except OSError:
+            session, started, steps, status = path.stem, None, 0, "UNREADABLE"
+        when = (datetime.fromtimestamp(started).strftime("%Y-%m-%d %H:%M:%S")
+                if started is not None else "-")
+        rows.append((started if started is not None else float("inf"), session, when, str(steps), status))
+    rows.sort(key=lambda r: (r[0], r[1]))
+    table = [("SESSION", "STARTED", "STEPS", "VERIFIES")] + [r[1:] for r in rows]
+    widths = [max(len(r[i]) for r in table) for i in range(4)]
+    for r in table:
+        print("  ".join(c.ljust(widths[i]) for i, c in enumerate(r)).rstrip())
+    return EXIT_OK
+
+
+def cmd_demo(args) -> int:
+    """Run the scripted stuck-agent scenario in a temp directory (local backend, no Docker)."""
+    from .agent import ScriptedModel, run_agent
+    from .recorder import Recorder
+
+    missing = [t for t in ("bash", "python3") if shutil.which(t) is None]
+    if missing:
+        raise CliError("the demo needs " + " and ".join(missing) + " on your PATH")
+    with tempfile.TemporaryDirectory(prefix="agentbox-demo-") as tmp:
+        tmp = Path(tmp)
+        key_path = tmp / "key"              # throwaway key: the demo never touches ~/.agentbox
+        rec = Recorder("demo", workspace=str(tmp / "workspace"), log_dir=str(tmp / "runs"),
+                       key_path=key_path)
+        print("agentbox demo: a scripted agent repeats a failing command, gets a hint, recovers.\n")
+        try:
+            out = run_agent("Make main.py run without errors.", ScriptedModel(), rec)
+        finally:
+            rec.close("demo finished")      # every way a run stops is written to the log
+        print(f"\nResult: {out}\n")
+        print("--- agentbox report ---")
+        cmd_report(argparse.Namespace(logfile=rec.log_path))
+        print("\n--- agentbox verify ---")
+        code = _verify_and_print(rec.log_path, load_or_create_key(key_path))
+        print("\n(This ran in a temporary directory that is deleted when the command exits.)")
+    return code if code != EXIT_OK else (EXIT_OK if out["reason"] == "final_answer" else 1)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="agentbox")
+    p.add_argument("--version", action="version", version=f"agentbox {__version__}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+    v = sub.add_parser("verify", help="check a log for tampering")
+    v.add_argument("logfile")
+    v.set_defaults(fn=cmd_verify)
+    r = sub.add_parser("report", help="print a readable summary")
+    r.add_argument("logfile")
+    r.add_argument(
+        "--format", "-f",
+        choices=["text", "json", "html"],
+        default="text",
+        help="output format (text, json, html; default: text)",
+    )
+    r.add_argument(
+        "--output", "-o",
+        default=None,
+        help="write report to a file instead of stdout",
+    )
+    r.set_defaults(fn=cmd_report)
+    ls = sub.add_parser("list", help="list the logs in a directory (default: ./runs)")
+    ls.add_argument("directory", nargs="?", default="runs")
+    ls.set_defaults(fn=cmd_list)
+    d = sub.add_parser("demo", help="run a self-contained demo (no Docker, no API key)")
+    d.set_defaults(fn=cmd_demo)
+    return p
+
+
+def main(argv=None) -> int:
+    if argv is not None:
+        argv = [str(a) for a in argv]
+    args = build_parser().parse_args(argv)
+    try:
+        return args.fn(args)
+    except CliError as e:
+        print(f"agentbox: error: {e}", file=sys.stderr)
+        return EXIT_ERROR
+
+
+if __name__ == "__main__":
+    sys.exit(main())

agentbox/docker_backend.py

@@ -0,0 +1,167 @@
+"""Run agent commands inside an isolated Docker container (v0.2).
+
+The signing key and log files stay on the HOST. The container only sees
+the workspace folder, has no network by default, a read-only filesystem,
+no Linux capabilities, and resource limits.
+"""
+import os
+import subprocess
+import threading
+import time
+import uuid
+
+from .executor import build_observation
+from .sandbox_stats import EventCounter, parse_state, parse_stats
+from .streaming import DEFAULT_MAX_STREAM_BYTES, run_streaming
+
+DEFAULT_IMAGE = "python:3.12-slim"
+
+
+class DockerNotAvailable(RuntimeError):
+    pass
+
+
+def container_user() -> str:
+    """The uid:gid the container runs as.
+
+    Unix: the host user, so the mounted workspace stays writable.
+    Windows has no uid or gid. Docker Desktop makes bind mounts writable for any user,
+    so a fixed non-root user is used. The sandbox is never run as root by default.
+    """
+    getuid, getgid = getattr(os, "getuid", None), getattr(os, "getgid", None)
+    if getuid and getgid:
+        return f"{getuid()}:{getgid()}"
+    return "1000:1000"
+
+
+def docker_available() -> bool:
+    try:
+        r = subprocess.run(["docker", "info"], capture_output=True, timeout=20)
+        return r.returncode == 0
+    except (OSError, subprocess.TimeoutExpired):
+        return False
+
+
+class DockerSandbox:
+    def __init__(self, workspace="./workspace-docker", image=DEFAULT_IMAGE,
+                 network="none", memory="512m", cpus="1", pids=128, resource_stats=True, user=None):
+        self.workspace = os.path.abspath(workspace)
+        self.image, self.network = image, network
+        self.memory, self.cpus, self.pids = memory, cpus, pids
+        self.name = f"agentbox-{uuid.uuid4().hex[:8]}"
+        self.started = False
+        self.resource_stats = resource_stats   # adds about a second per step
+        self.user = user or container_user()   # "uid:gid"; override if needed
+        self.events = EventCounter()
+        self._events_proc = None
+
+    def describe(self) -> dict:
+        return {"backend": "docker", "image": self.image, "network": self.network,
+                "memory": self.memory, "cpus": self.cpus, "pids_limit": self.pids,
+                "read_only_rootfs": True, "cap_drop": "ALL", "resource_stats": self.resource_stats, "user": self.user}
+
+    def start(self):
+        if not docker_available():
+            raise DockerNotAvailable("Docker is not running or not installed.")
+        os.makedirs(self.workspace, exist_ok=True)
+        cmd = [
+            "docker", "run", "-d", "--rm", "--name", self.name,
+            "--network", self.network,
+            "--read-only",
+            "--tmpfs", "/tmp:rw,noexec,nosuid,size=64m",
+            "--cap-drop", "ALL",
+            "--security-opt", "no-new-privileges:true",
+            "--pids-limit", str(self.pids),
+            "--memory", self.memory, "--memory-swap", self.memory,
+            "--cpus", str(self.cpus),
+            "--user", self.user,
+            "-e", "HOME=/tmp",
+            "-v", f"{self.workspace}:/workspace",
+            "-w", "/workspace",
+            self.image, "sleep", "infinity",
+        ]
+        r = subprocess.run(cmd, capture_output=True, text=True)
+        if r.returncode != 0:
+            raise DockerNotAvailable(f"Could not start container: {r.stderr.strip()}")
+        self.started = True
+        self._start_event_watcher()
+
+    def stop(self):
+        if self.started:
+            self._stop_event_watcher()
+            subprocess.run(["docker", "rm", "-f", self.name], capture_output=True)
+            self.started = False
+
+    def _start_event_watcher(self):
+        """Follow `docker events` for this container (host side, so the agent cannot touch it)."""
+        since = str(int(time.time()) - 2)     # --since avoids missing events during start-up
+        try:
+            proc = subprocess.Popen(
+                ["docker", "events", "--since", since, "--filter", f"container={self.name}",
+                 "--format", "{{json .}}"],
+                stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True)
+        except OSError:
+            return
+        self._events_proc = proc
+
+        def pump():
+            for line in proc.stdout:
+                self.events.feed(line)
+
+        threading.Thread(target=pump, daemon=True).start()
+
+    def _stop_event_watcher(self):
+        if self._events_proc is not None:
+            self._events_proc.terminate()
+            self._events_proc = None
+
+    def _snapshot(self, oom_before: int, code: int, exceeded: bool) -> dict:
+        """What Docker says about the container after a step. Never raises."""
+        snap: dict = {}
+        try:
+            r = subprocess.run(["docker", "inspect", "--format", "{{json .State}}", self.name],
+                               capture_output=True, text=True, timeout=15)
+            snap.update(parse_state(r.stdout))
+        except (OSError, subprocess.TimeoutExpired):
+            pass
+        if self.resource_stats and snap.get("running", True):
+            try:
+                r = subprocess.run(["docker", "stats", "--no-stream", "--format", "{{json .}}", self.name],
+                                   capture_output=True, text=True, timeout=30)
+                lines = r.stdout.strip().splitlines()
+                snap.update(parse_stats(lines[0] if lines else ""))
+            except (OSError, subprocess.TimeoutExpired):
+                pass
+        if code == 137 and not exceeded:        # a kill: give the OOM event a moment to arrive
+            deadline = time.monotonic() + 2.0
+            while self.events.count("oom") == oom_before and time.monotonic() < deadline:
+                time.sleep(0.1)
+        snap["oom_events"] = self.events.count("oom") - oom_before
+        return snap
+
+    def _kill_stragglers(self):
+        """Kill everything in the container except PID 1 (the idle `sleep`)."""
+        try:
+            subprocess.run(["docker", "exec", self.name, "sh", "-c", 'for p in /proc/[0-9]*; do pid=${p#/proc/}; if [ "$pid" -gt 1 ] && [ "$pid" != "$$" ]; then kill -9 "$pid" 2>/dev/null; fi; done'],
+                           capture_output=True, timeout=15)
+        except (OSError, subprocess.TimeoutExpired):
+            pass
+
+    def run(self, cmd: str, timeout_s: int = 60,
+            max_output_bytes: int = DEFAULT_MAX_STREAM_BYTES) -> dict:
+        if not self.started:
+            raise RuntimeError("Call start() before run().")
+        argv = ["docker", "exec", "-w", "/workspace", self.name,
+                "timeout", "-k", "2", str(timeout_s),
+                "bash", "--noprofile", "--norc", "-c", cmd]
+        oom_before = self.events.count("oom")
+        t0 = time.monotonic()
+        # The in-container `timeout` is the normal deadline (exit 124); the host-side
+        # deadline is a backstop if `docker exec` itself hangs.
+        code, out, err, timed_out, exceeded = run_streaming(
+            argv, cwd=None, timeout_s=timeout_s + 10, max_bytes=max_output_bytes,
+            cleanup=self._kill_stragglers)
+        obs = build_observation(cmd, code, out, err, timed_out or code == 124, exceeded,
+                                self.workspace, int((time.monotonic() - t0) * 1000))
+        obs["sandbox"] = self._snapshot(oom_before, code, exceeded)
+        return obs

agentbox/error_signatures.py

@@ -0,0 +1,46 @@
+"""Language-specific error extractors for error signatures.
+
+Each extractor returns (error_class, key_message) or None when the text does not
+look like that language's error output. Only the stable part of an error is
+returned (class + message), never stack frames, so the same failure produces the
+same signature even when line numbers, paths or versions change.
+"""
+import re
+
+# --- Go -------------------------------------------------------------------
+_GO_PANIC = re.compile(r"^panic: (.+)$", re.M)
+_GO_FATAL = re.compile(r"^fatal error: (.+)$", re.M)
+_GO_COMPILE = re.compile(r"^\S*\.go:\d+(?::\d+)?: (.+)$", re.M)
+
+# --- Node.js --------------------------------------------------------------
+_NODE_HEADER = re.compile(
+    r"^(?:Uncaught\s+)?((?:[A-Za-z_$][\w$]*)?(?:Error|Exception))(?:\s+\[([A-Z0-9_]+)\])?:\s*(.*)$",
+    re.M,
+)
+_NODE_FRAME = re.compile(r"^\s+at \S", re.M)
+_NODE_VERSION = re.compile(r"^Node\.js v\d+", re.M)
+
+
+def extract_go(text: str):
+    m = _GO_PANIC.search(text)
+    if m:
+        return "GoPanic", m.group(1)
+    m = _GO_FATAL.search(text)
+    if m:
+        return "GoFatalError", m.group(1)
+    m = _GO_COMPILE.search(text)
+    if m:
+        return "GoCompileError", m.group(1)
+    return None
+
+
+def extract_node(text: str):
+    # Require Node-style stack frames or the version footer, so a bare
+    # "Error: ..." line from some other tool is not misclassified.
+    if not (_NODE_FRAME.search(text) or _NODE_VERSION.search(text)):
+        return None
+    m = _NODE_HEADER.search(text)
+    if not m:
+        return None
+    cls, code, msg = m.groups()
+    return (f"{cls}[{code}]" if code else cls), msg