agentboxx 0.2.1__py3-none-any.whl

agentbox/executor.py

@@ -0,0 +1,102 @@
+"""Runs a shell command and observes it from the outside."""
+import hashlib
+import os
+import re
+import time
+
+from .error_signatures import extract_go, extract_node
+from .redact import redact_all
+from .streaming import DEFAULT_MAX_STREAM_BYTES, run_streaming
+from .workspace import workspace_hash
+
+_NORMALIZERS = [
+    (re.compile(r"0x[0-9a-fA-F]+"), "<HEX>"),
+    (re.compile(r"\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b"), "<UUID>"),
+    (re.compile(r"/tmp/\S+"), "/tmp/<TMP>"),
+    (re.compile(r"\d+"), "<N>"),
+    (re.compile(r"\s+"), " "),
+]
+_ERR_CLASS = re.compile(r"^([A-Za-z_][\w.]*(?:Error|Exception))\b", re.M)
+MAX_KEEP = 4000
+
+
+def normalize(text: str) -> str:
+    for rx, rep in _NORMALIZERS:
+        text = rx.sub(rep, text)
+    return text.strip().lower()
+
+
+def fingerprint(text: str) -> str:
+    return hashlib.sha256(normalize(text).encode()).hexdigest()[:16]
+
+
+def error_signature(stderr: str, exit_code: int):
+    if exit_code == 0 or not stderr.strip():
+        return None, None
+    if "Traceback (most recent call last)" not in stderr:
+        found = extract_go(stderr) or extract_node(stderr)
+        if found:
+            cls, msg = found
+            return f"{cls}:{fingerprint(cls + ' ' + msg)}", cls
+    last = [ln for ln in stderr.strip().splitlines() if ln.strip()][-3:]
+    classes = _ERR_CLASS.findall(stderr)
+    cls = classes[-1] if classes else None
+    sig = fingerprint("\n".join(last))
+    return (f"{cls}:{sig}" if cls else sig), cls
+
+
+def _clip(s: str) -> dict:
+    return {
+        "text": s if len(s) <= MAX_KEEP else s[: MAX_KEEP // 2] + "\n...[truncated]...\n" + s[-MAX_KEEP // 2 :],
+        "total_chars": len(s),
+        "sha256": hashlib.sha256(s.encode()).hexdigest(),
+    }
+
+
+def _txt(x) -> str:
+    if x is None:
+        return ""
+    return x.decode("utf-8", "replace") if isinstance(x, bytes) else x
+
+
+def _stream_record(text: str, cap) -> dict:
+    # total_chars is kept for compatibility; it counts bytes seen on the stream.
+    return {
+        "text": text,
+        "total_chars": cap.total,
+        "total_bytes": cap.total,
+        "truncated": cap.truncated,
+        "sha256": hashlib.sha256(text.encode()).hexdigest(),   # of the stored, redacted text
+    }
+
+
+def build_observation(cmd, code, out, err, timed_out, exceeded, workspace, duration_ms) -> dict:
+    """Turn a finished command into a log record. Used by every backend."""
+    out_text, err_text = out.text(), err.text()
+    cmd, out_text, err_text, redactions = redact_all(cmd, out_text, err_text)
+    sig, cls = error_signature(err_text, code)
+    return {
+        "redactions": redactions,
+        "command": cmd,
+        "command_fingerprint": fingerprint(cmd),
+        "exit_code": code,
+        "timed_out": timed_out,
+        "output_limit_exceeded": exceeded,
+        "stdout": _stream_record(out_text, out),
+        "stderr": _stream_record(err_text, err),
+        "error_signature": sig,
+        "error_class": cls,
+        "workspace_hash": workspace_hash(workspace),
+        "duration_ms": duration_ms,
+    }
+
+
+def run_command(cmd: str, workspace: str, timeout_s: int = 60,
+                max_output_bytes: int = DEFAULT_MAX_STREAM_BYTES) -> dict:
+    os.makedirs(workspace, exist_ok=True)
+    t0 = time.monotonic()
+    code, out, err, timed_out, exceeded = run_streaming(
+        ["bash", "--noprofile", "--norc", "-c", cmd],
+        cwd=workspace, timeout_s=timeout_s, max_bytes=max_output_bytes)
+    return build_observation(cmd, code, out, err, timed_out, exceeded, workspace,
+                             int((time.monotonic() - t0) * 1000))

agentbox/loop_detector.py

@@ -0,0 +1,71 @@
+"""Detects an agent that is stuck."""
+from collections import deque
+from dataclasses import dataclass
+
+
+@dataclass
+class LoopConfig:
+    window: int = 10
+    exact_warn: int = 3
+    exact_crit: int = 5
+    error_warn: int = 3
+    error_crit: int = 5
+    no_progress_warn: int = 4
+
+
+class LoopDetector:
+    def __init__(self, cfg: LoopConfig | None = None):
+        self.cfg = cfg or LoopConfig()
+        self.win: deque = deque(maxlen=self.cfg.window)
+
+    def observe(self, step: dict) -> list[dict]:
+        self.win.append(step)
+        signals = []
+        signals += self._exact(step)
+        signals += self._error_repeat(step)
+        signals += self._no_progress()
+        signals += self._cycle()
+        return signals
+
+    @staticmethod
+    def _sig(kind, severity, count, hint):
+        return {"kind": kind, "severity": severity, "count": count, "hint": hint}
+
+    def _exact(self, s):
+        n = sum(1 for x in self.win if x["command_fingerprint"] == s["command_fingerprint"]
+                and x["workspace_hash"] == s["workspace_hash"])   # same command on unchanged files
+        if n >= self.cfg.exact_crit:
+            return [self._sig("loop.exact", "critical", n, "Same command repeated. Stop and change approach.")]
+        if n >= self.cfg.exact_warn:
+            return [self._sig("loop.exact", "warn", n, "Same command repeated. Try something different.")]
+        return []
+
+    def _error_repeat(self, s):
+        if not s.get("error_signature"):
+            return []
+        n = sum(1 for x in self.win if x.get("error_signature") == s["error_signature"])
+        if n >= self.cfg.error_crit:
+            return [self._sig("loop.error_repeat", "critical", n, "Same error again and again. Re-plan.")]
+        if n >= self.cfg.error_warn:
+            return [self._sig("loop.error_repeat", "warn", n, "Same error recurring. Form a new hypothesis.")]
+        return []
+
+    def _no_progress(self):
+        steps = list(self.win)
+        run = 0
+        for x in reversed(steps):
+            if x["workspace_hash"] == steps[-1]["workspace_hash"]:
+                run += 1
+            else:
+                break
+        failing = sum(1 for x in steps[-run:] if x["exit_code"] != 0)
+        if run >= self.cfg.no_progress_warn and failing >= max(1, int(run * 0.8)):
+            return [self._sig("loop.no_progress", "warn", run, "No files changed across several failing steps.")]
+        return []
+
+    def _cycle(self):
+        seq = [x["command_fingerprint"] for x in self.win]
+        for L in (2, 3):
+            if len(seq) >= 2 * L and seq[-L:] == seq[-2 * L : -L] and len(set(seq[-L:])) > 1:
+                return [self._sig("loop.cycle", "warn", 2, f"Repeating a cycle of {L} commands.")]
+        return []

agentbox/recorder.py

@@ -0,0 +1,73 @@
+"""The main API. Wrap every action your agent takes in `recorder.run(...)`."""
+from pathlib import Path
+
+from .executor import run_command
+from .loop_detector import LoopConfig, LoopDetector
+from .redact import merge_counts, redact
+from .signer import ChainWriter, load_or_create_key
+
+
+def _crash_kind(sbx: dict):
+    if sbx.get("oom_events", 0) > 0 or sbx.get("oom_killed"):
+        return "oom_kill"
+    if sbx.get("running") is False:
+        return "container_stopped"
+    return None
+
+
+class Recorder:
+    def __init__(self, session_id: str, workspace: str = "./workspace",
+                 log_dir: str = "./runs", key_path=None,
+                 loop_cfg: LoopConfig | None = None, sandbox=None,
+                 overwrite: bool = False, agent_id: str | None = None):
+        self.session_id, self.workspace, self.sandbox = session_id, workspace, sandbox
+        self.agent_id = agent_id
+        self.log_path = Path(log_dir) / f"{session_id}.ndjson"
+        self.writer = ChainWriter(self.log_path, load_or_create_key(key_path), overwrite=overwrite)
+        self.detector = LoopDetector(loop_cfg)
+        self.step_index = 0
+        isolation = sandbox.describe() if sandbox else {"backend": "local"}
+        start = {"session_id": session_id, "isolation": isolation}
+        if agent_id:
+            start["agent_id"] = agent_id
+        self.writer.append("session.start", start)
+
+    def run(self, command: str, thought: str = "", timeout_s: int = 60, *,
+            tool: str | None = None, parent_step: int | None = None,
+            usage: dict | None = None) -> dict:
+        self.step_index += 1
+        if self.sandbox:
+            obs = self.sandbox.run(command, timeout_s)
+        else:
+            obs = run_command(command, self.workspace, timeout_s)
+        sbx = obs.pop("sandbox", None)      # reported as separate events, not inside the step
+        thought, t_counts = redact(thought)
+        redactions = merge_counts(obs.get("redactions", {}), t_counts)
+        step = {"session_id": self.session_id, "step_index": self.step_index,
+                "thought": thought, **obs, "redactions": redactions}
+        if self.agent_id:
+            step["agent_id"] = self.agent_id
+        if tool:
+            step["tool"] = tool
+        if parent_step is not None:
+            step["parent_step_index"] = int(parent_step)
+        if usage:
+            step["usage"] = {str(k): int(v) for k, v in usage.items()}   # from the caller, never computed
+        self.writer.append("step", step)
+        if sbx:
+            metrics = {k: sbx.get(k) for k in ("mem_bytes", "mem_limit_bytes", "mem_pct", "cpu_pct", "pids")}
+            self.writer.append("sandbox.resource", {"step_index": self.step_index, **metrics})
+            kind = _crash_kind(sbx)
+            if kind:
+                self.writer.append("sandbox.crash", {"step_index": self.step_index, "kind": kind,
+                                                     "exit_code": obs.get("exit_code"), **sbx})
+        signals = self.detector.observe(step)
+        for s in signals:
+            self.writer.append("analysis.signal", {"step_index": self.step_index, **s})
+        return {"observation": obs, "signals": signals, "sandbox": sbx}
+
+    def close(self, reason: str = "done"):
+        self.writer.append("session.end", {"reason": reason, "steps": self.step_index})
+        self.writer.write_manifest()
+        if self.sandbox:
+            self.sandbox.stop()

agentbox/redact.py

@@ -0,0 +1,71 @@
+"""Redact secrets from text before it is logged and signed.
+
+Once a record is signed it cannot be edited, so secrets must be removed first.
+Only a count per pattern is recorded, never the value. Patterns are heuristics:
+they will miss some secrets and occasionally hide harmless values. Add your own
+with add_pattern().
+"""
+import re
+
+_NAME = (r"[A-Za-z0-9_.-]*(?:password|passwd|secret|token|api[_-]?key|"
+         r"access[_-]?key|private[_-]?key)[A-Za-z0-9_.-]*")
+_NOT_DONE = r"(?!\[REDACTED:)"   # do not re-redact text a specific pattern already replaced
+
+# (name, compiled regex, replacement). Specific token formats come first,
+# context-based patterns (headers, URLs, KEY=value) last.
+PATTERNS = [
+    ("private_key", re.compile(
+        r"-----BEGIN [A-Z ]*PRIVATE KEY-----.*?(?:-----END [A-Z ]*PRIVATE KEY-----|\Z)", re.S),
+     "[REDACTED:private_key]"),
+    ("aws_key", re.compile(r"\b(?:AKIA|ASIA)[0-9A-Z]{16}\b"), "[REDACTED:aws_key]"),
+    ("github_token", re.compile(
+        r"\b(?:gh[pousr]_[A-Za-z0-9]{30,}|github_pat_[A-Za-z0-9_]{20,})\b"),
+     "[REDACTED:github_token]"),
+    ("api_key", re.compile(r"\bsk-[A-Za-z0-9_-]{20,}"), "[REDACTED:api_key]"),
+    ("slack_token", re.compile(r"\bxox[abprs]-[A-Za-z0-9-]{10,}"), "[REDACTED:slack_token]"),
+    ("google_key", re.compile(r"\bAIza[0-9A-Za-z_-]{35}\b"), "[REDACTED:google_key]"),
+    ("jwt", re.compile(
+        r"\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}"),
+     "[REDACTED:jwt]"),
+    ("auth_header", re.compile(
+        r"(?i)(\bauthorization\s*[:=]\s*(?:bearer|basic|token)\s+)" + _NOT_DONE + r"[^\s'\"]+"),
+     r"\1[REDACTED:auth_header]"),
+    ("url_password", re.compile(
+        r"(?i)\b([a-z][a-z0-9+.-]*://[^\s:/@]+:)" + _NOT_DONE + r"[^\s@/]+(@)"),
+     r"\1[REDACTED:url_password]\2"),
+    ("secret_assignment", re.compile(
+        r"(?i)(\b" + _NAME + r"\s*[:=]\s*)(['\"]?)" + _NOT_DONE + r"[^\s'\";&]{6,}(\2)"),
+     r"\1\2[REDACTED:secret_assignment]\3"),
+]
+
+
+def add_pattern(name: str, regex: str, replacement: str | None = None):
+    """Register an extra pattern, e.g. add_pattern('internal_id', r'INT-[0-9]{8}')."""
+    PATTERNS.append((name, re.compile(regex), replacement or f"[REDACTED:{name}]"))
+
+
+def redact(text: str):
+    """Return (clean_text, counts) where counts maps pattern name to matches."""
+    counts: dict[str, int] = {}
+    if not text:
+        return text, counts
+    for name, rx, repl in PATTERNS:
+        text, n = rx.subn(repl, text)
+        if n:
+            counts[name] = counts.get(name, 0) + n
+    return text, counts
+
+
+def merge_counts(*parts: dict) -> dict:
+    total: dict[str, int] = {}
+    for part in parts:
+        for k, v in part.items():
+            total[k] = total.get(k, 0) + v
+    return total
+
+
+def redact_all(cmd: str, out: str, err: str):
+    cmd, c1 = redact(cmd)
+    out, c2 = redact(out)
+    err, c3 = redact(err)
+    return cmd, out, err, merge_counts(c1, c2, c3)

agentbox/report.py

@@ -0,0 +1,266 @@
+"""Report generation for agentbox runs: text, structured JSON, and self-contained HTML."""
+import html
+import json
+from datetime import datetime
+from typing import Any, Dict, List
+
+_RED = "\033[31m"
+_YELLOW = "\033[33m"
+_RESET = "\033[0m"
+
+
+def _paint(text: str, color: str, enabled: bool) -> str:
+    return f"{color}{text}{_RESET}" if enabled else text
+
+
+def build_report_data(events: List[Dict[str, Any]]) -> Dict[str, Any]:
+    """Aggregate raw log events into a clean structured dictionary."""
+    session_info: Dict[str, Any] = {
+        "session_id": "unknown",
+        "isolation": {},
+        "agent_id": None,
+        "started_at": None,
+        "ended_at": None,
+        "duration_s": None,
+        "reason": None,
+    }
+    steps: List[Dict[str, Any]] = []
+    signals: List[Dict[str, Any]] = []
+    resources: List[Dict[str, Any]] = []
+    crashes: List[Dict[str, Any]] = []
+    total_redactions = 0
+
+    for ev in events:
+        etype = ev.get("event_type")
+        ts = ev.get("ts")
+        data = ev.get("data") or {}
+
+        if etype == "session.start":
+            session_info["session_id"] = data.get("session_id", "unknown")
+            session_info["isolation"] = data.get("isolation", {})
+            session_info["agent_id"] = data.get("agent_id")
+            session_info["started_at"] = ts
+        elif etype == "session.end":
+            session_info["ended_at"] = ts
+            session_info["reason"] = data.get("reason")
+        elif etype == "step":
+            steps.append(data)
+            red = data.get("redactions")
+            if isinstance(red, dict):
+                total_redactions += sum(red.values())
+        elif etype == "analysis.signal":
+            signals.append(data)
+        elif etype == "sandbox.resource":
+            resources.append(data)
+        elif etype == "sandbox.crash":
+            crashes.append(data)
+
+    if session_info["started_at"] is not None and session_info["ended_at"] is not None:
+        session_info["duration_s"] = round(session_info["ended_at"] - session_info["started_at"], 3)
+
+    successful = sum(1 for s in steps if s.get("exit_code") == 0)
+    failed = len(steps) - successful
+
+    return {
+        "session": session_info,
+        "summary": {
+            "total_steps": len(steps),
+            "successful_steps": successful,
+            "failed_steps": failed,
+            "signals": len(signals),
+            "crashes": len(crashes),
+            "total_redactions": total_redactions,
+        },
+        "steps": steps,
+        "signals": signals,
+        "sandbox_resources": resources,
+        "sandbox_crashes": crashes,
+    }
+
+
+def render_text(data: Dict[str, Any], color: bool = False) -> str:
+    """Render the human-readable terminal report matching standard cli format."""
+    lines: List[str] = []
+    steps = data.get("steps", [])
+    signals = data.get("signals", [])
+    crashes = data.get("sandbox_crashes", [])
+
+    for d in steps:
+        ok = d.get("exit_code") == 0
+        mark = "ok " if ok else _paint("ERR", _RED, color)
+        cmd_str = (d.get("command") or "")[:70]
+        step_idx = d.get("step_index", 0)
+        exit_code = d.get("exit_code", -1)
+        lines.append(f"[{step_idx:>3}] {mark} exit={exit_code:<3} {cmd_str}")
+
+    lines.append(f"\n{len(steps)} steps, {len(signals)} signals")
+
+    for s in signals:
+        line = f"  step {s['step_index']}: [{s['severity']}] {s['kind']} (x{s['count']}) - {s['hint']}"
+        if s.get("severity") == "critical":
+            line = _paint(line, _RED, color)
+        elif s.get("severity") == "warn":
+            line = _paint(line, _YELLOW, color)
+        lines.append(line)
+
+    for c in crashes:
+        line = f"  step {c.get('step_index', '?')}: crash [{c.get('kind', 'unknown')}] exit={c.get('exit_code')} (oom={c.get('oom_killed')})"
+        line = _paint(line, _RED, color)
+        lines.append(line)
+
+    return "\n".join(lines) + "\n"
+
+
+def render_json(data: Dict[str, Any]) -> str:
+    """Render report as indented JSON."""
+    return json.dumps(data, indent=2, ensure_ascii=False) + "\n"
+
+_HTML_CSS = """
+:root {
+  --bg: #0d1117; --card-bg: #161b22; --border: #30363d;
+  --text: #c9d1d9; --text-muted: #8b949e; --accent: #58a6ff;
+  --green: #3fb950; --red: #f85149; --yellow: #d29922; --mono: monospace;
+}
+@media (prefers-color-scheme: light) {
+  :root {
+    --bg: #f6f8fa; --card-bg: #ffffff; --border: #d0d7de;
+    --text: #1f2328; --text-muted: #656d76; --accent: #0969da;
+    --green: #1a7f37; --red: #cf222e; --yellow: #9a6700;
+  }
+}
+* { box-sizing: border-box; margin: 0; padding: 0; }
+body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+      background: var(--bg); color: var(--text); padding: 2rem 1rem; line-height: 1.5; }
+.container { max-width: 960px; margin: 0 auto; }
+header { border-bottom: 1px solid var(--border); padding-bottom: 1.5rem; margin-bottom: 2rem; }
+h1 { font-size: 1.75rem; margin-bottom: 0.5rem; }
+.subtitle { color: var(--text-muted); font-size: 0.9rem; }
+.cards { display: grid; grid-template-columns: repeat(auto-fit, minmax(140px, 1fr)); gap: 1rem; margin-bottom: 2rem; }
+.card { background: var(--card-bg); border: 1px solid var(--border); border-radius: 6px; padding: 1rem; }
+.card-label { font-size: 0.75rem; text-transform: uppercase; color: var(--text-muted); }
+.card-val { font-size: 1.5rem; font-weight: bold; margin-top: 0.25rem; }
+.badge { display: inline-block; padding: 0.15rem 0.5rem; border-radius: 12px; font-size: 0.75rem; font-weight: 600; }
+.badge-ok { background: rgba(63,185,80,0.15); color: var(--green); }
+.badge-err { background: rgba(248,81,73,0.15); color: var(--red); }
+.badge-warn { background: rgba(210,153,34,0.15); color: var(--yellow); }
+section { margin-bottom: 2.5rem; }
+h2 { font-size: 1.25rem; margin-bottom: 1rem; border-bottom: 1px solid var(--border); padding-bottom: 0.5rem; }
+.timeline { display: flex; flex-direction: column; gap: 0.75rem; }
+.step-card { background: var(--card-bg); border: 1px solid var(--border); border-radius: 6px; padding: 0.75rem 1rem; }
+.step-header { display: flex; justify-content: space-between; align-items: baseline; gap: 1rem; }
+.step-cmd { font-family: var(--mono); font-size: 0.9rem; color: var(--accent); word-break: break-all; }
+.step-meta { font-size: 0.8rem; color: var(--text-muted); white-space: nowrap; }
+details { margin-top: 0.5rem; border-top: 1px dashed var(--border); padding-top: 0.5rem; font-size: 0.85rem; }
+summary { cursor: pointer; color: var(--text-muted); user-select: none; }
+summary:hover { color: var(--text); }
+pre { font-family: var(--mono); background: rgba(0,0,0,0.15); padding: 0.5rem; border-radius: 4px; overflow-x: auto; margin-top: 0.5rem; }
+.signal-box { background: rgba(210,153,34,0.1); border-left: 4px solid var(--yellow); padding: 0.75rem 1rem; margin-bottom: 0.75rem; border-radius: 0 4px 4px 0; }
+.signal-box.critical { background: rgba(248,81,73,0.1); border-left-color: var(--red); }
+"""
+
+
+def render_html(data: Dict[str, Any]) -> str:
+    """Render a single, completely self-contained HTML report with zero external assets."""
+    sess = data.get("session", {})
+    summary = data.get("summary", {})
+    steps = data.get("steps", [])
+    signals = data.get("signals", [])
+    crashes = data.get("sandbox_crashes", [])
+
+    started_str = (datetime.fromtimestamp(sess["started_at"]).strftime("%Y-%m-%d %H:%M:%S")
+                   if sess.get("started_at") else "unknown")
+    iso = sess.get("isolation", {})
+    backend_str = iso.get("backend", "local")
+    if iso.get("image"):
+        backend_str += f" ({iso.get('image')})"
+
+    out = [
+        "<!DOCTYPE html>",
+        '<html lang="en">',
+        "<head>",
+        '<meta charset="utf-8">',
+        '<meta name="viewport" content="width=device-width, initial-scale=1.0">',
+        f"<title>agentbox report - {html.escape(str(sess.get('session_id')))}</title>",
+        f"<style>{_HTML_CSS}</style>",
+        "</head>",
+        "<body>",
+        '<div class="container">',
+        "<header>",
+        "<h1>agentbox flight report</h1>",
+        f'<div class="subtitle">Session: <strong>{html.escape(str(sess.get("session_id")))}</strong> &bull; '
+        f'Started: {html.escape(started_str)} &bull; '
+        f'Backend: {html.escape(backend_str)}'
+        f'{(" &bull; Agent: " + html.escape(str(sess["agent_id"]))) if sess.get("agent_id") else ""}</div>',
+        "</header>",
+        '<div class="cards">',
+        f'<div class="card"><div class="card-label">Steps</div><div class="card-val">{summary.get("total_steps", 0)}</div></div>',
+        f'<div class="card"><div class="card-label">Passed</div><div class="card-val">{summary.get("successful_steps", 0)}</div></div>',
+        f'<div class="card"><div class="card-label">Failed</div><div class="card-val">{summary.get("failed_steps", 0)}</div></div>',
+        f'<div class="card"><div class="card-label">Signals</div><div class="card-val">{summary.get("signals", 0)}</div></div>',
+        f'<div class="card"><div class="card-label">Duration</div><div class="card-val">{sess.get("duration_s", 0)}s</div></div>',
+        "</div>",
+    ]
+
+    if signals:
+        out.append("<section><h2>Detector Signals</h2>")
+        for s in signals:
+            sev = s.get("severity", "warn")
+            cls = "critical" if sev == "critical" else "warn"
+            out.append(
+                f'<div class="signal-box {cls}">'
+                f'<strong>Step {s.get("step_index")}: [{html.escape(sev)}] {html.escape(s.get("kind", ""))}</strong> '
+                f'(fired {s.get("count")}x)<br>'
+                f'{html.escape(s.get("hint", ""))}'
+                f'</div>'
+            )
+        out.append("</section>")
+
+    if crashes:
+        out.append("<section><h2>Sandbox Crashes</h2>")
+        for c in crashes:
+            out.append(
+                f'<div class="signal-box critical">'
+                f'<strong>Step {c.get("step_index", "?")}: Crash - {html.escape(str(c.get("kind")))}</strong> '
+                f'(exit {c.get("exit_code")}, oom={c.get("oom_killed")})'
+                f'</div>'
+            )
+        out.append("</section>")
+
+    out.append("<section><h2>Step Timeline</h2><div class=\"timeline\">")
+    for s in steps:
+        ec = s.get("exit_code", 0)
+        badge_cls = "badge-ok" if ec == 0 else "badge-err"
+        badge_txt = "OK" if ec == 0 else f"ERR ({ec})"
+        dur = f"{s.get('duration_ms', 0)}ms"
+        cmd = s.get("command", "")
+        out.append(
+            f'<div class="step-card">'
+            f'<div class="step-header">'
+            f'<div><span class="badge {badge_cls}">{badge_txt}</span> '
+            f'<strong>#{s.get("step_index")}</strong> '
+            f'<span class="step-cmd">{html.escape(cmd)}</span></div>'
+            f'<span class="step-meta">{html.escape(dur)}</span>'
+            f'</div>'
+        )
+        details_items = []
+        if s.get("thought"):
+            details_items.append(f'<p><strong>Thought:</strong> {html.escape(s["thought"])}</p>')
+        if s.get("tool"):
+            details_items.append(f'<p><strong>Tool:</strong> {html.escape(str(s["tool"]))}</p>')
+        if s.get("error_class"):
+            details_items.append(f'<p><strong>Error Class:</strong> {html.escape(s["error_class"])}</p>')
+        if s.get("error_signature"):
+            details_items.append(f'<p><strong>Error Signature:</strong> <code>{html.escape(s["error_signature"])}</code></p>')
+        stdout_text = (s.get("stdout") or {}).get("text")
+        if stdout_text:
+            details_items.append(f'<p><strong>stdout:</strong><pre>{html.escape(stdout_text)}</pre></p>')
+        stderr_text = (s.get("stderr") or {}).get("text")
+        if stderr_text:
+            details_items.append(f'<p><strong>stderr:</strong><pre>{html.escape(stderr_text)}</pre></p>')
+        if details_items:
+            out.append(f'<details><summary>Details &amp; Output</summary>{"".join(details_items)}</details>')
+        out.append("</div>")
+
+    out.append("</div></section>")
+    out.append("</div></body></html>\n")
+    return "\n".join(out)

agentbox/sandbox_stats.py

@@ -0,0 +1,80 @@
+"""Parse what Docker reports about a container: state, resource use and events.
+
+These run on the HOST, so the sandboxed agent cannot influence them.
+"""
+import json
+import re
+import threading
+
+_UNITS = {"b": 1, "kb": 1000, "mb": 1000 ** 2, "gb": 1000 ** 3, "tb": 1000 ** 4,
+          "kib": 1024, "mib": 1024 ** 2, "gib": 1024 ** 3, "tib": 1024 ** 4}
+
+
+def parse_size(text):
+    """'12.5MiB' -> bytes. Returns None if it cannot be read."""
+    m = re.fullmatch(r"\s*([0-9]*\.?[0-9]+)\s*([A-Za-z]*)\s*", text or "")
+    if not m:
+        return None
+    unit = (m.group(2) or "b").lower()
+    if unit not in _UNITS:
+        return None
+    return int(float(m.group(1)) * _UNITS[unit])
+
+
+def _pct(text):
+    try:
+        return float(str(text).strip().rstrip("%"))
+    except ValueError:
+        return None
+
+
+def parse_stats(line: str) -> dict:
+    """One line of `docker stats --no-stream --format '{{json .}}'`."""
+    try:
+        d = json.loads(line)
+    except ValueError:
+        return {}
+    used, _, limit = str(d.get("MemUsage", "")).partition("/")
+    try:
+        pids = int(d.get("PIDs"))
+    except (TypeError, ValueError):
+        pids = None
+    return {"mem_bytes": parse_size(used), "mem_limit_bytes": parse_size(limit),
+            "mem_pct": _pct(d.get("MemPerc")), "cpu_pct": _pct(d.get("CPUPerc")),
+            "pids": pids}
+
+
+def parse_state(text: str) -> dict:
+    """Output of `docker inspect --format '{{json .State}}'`."""
+    try:
+        s = json.loads(text)
+    except ValueError:
+        return {}
+    if not isinstance(s, dict):
+        return {}
+    return {"running": bool(s.get("Running")), "oom_killed": bool(s.get("OOMKilled")),
+            "exit_code": s.get("ExitCode"), "error": s.get("Error") or None}
+
+
+class EventCounter:
+    """Counts container events (oom, die, ...) from `docker events --format '{{json .}}'`."""
+
+    def __init__(self):
+        self._lock = threading.Lock()
+        self._counts = {}
+
+    def feed(self, line: str):
+        try:
+            d = json.loads(line)
+        except ValueError:
+            return
+        if not isinstance(d, dict):
+            return
+        action = str(d.get("Action") or d.get("status") or "")
+        if action:
+            with self._lock:
+                self._counts[action] = self._counts.get(action, 0) + 1
+
+    def count(self, action: str) -> int:
+        with self._lock:
+            return self._counts.get(action, 0)