Skip to content

Replay your coding agent sessions as a map and a timeline

feat: search index, Run health, fix writer and Autotune (Python side)

aiswaryasankartest3fc8edf623ce
diff --git a/python/src/agentplay/autotune.py b/python/src/agentplay/autotune.py
new file mode 100644
index 0000000..418235b
--- /dev/null
+++ b/python/src/agentplay/autotune.py
@@ -0,0 +1,269 @@
+"""Autotune: apply Run health fixes daily, ask before anything that grants access, retire what does not help.
+
+Off until turned on for a repo. Each run (at most once a day unless forced):
+
+1. Computes fixes over the last 30 days of root sessions (``health.fixes``).
+2. For each repo that is both granted (``fixes.grant``) and enabled here:
+ * an instruction fix is written inside the managed block of
+ ``CLAUDE.local.md`` (personal, git-ignored), or of the shared
+ ``CLAUDE.md`` when the repo's ``claudeMd`` setting is ``auto``;
+ * a permission or hook fix is queued for the person to approve.
+3. Measures every fix it applied on that fix's own metric over the sessions
+ since. After 15 sessions with less than a 10% improvement the fix is
+ undone and logged as retired.
+
+State lives in ``~/.agentplay/autotune.json``; writes go through ``fixes.apply``.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+from . import facts, fixes, health
+
+CONFIG = "autotune.json"
+WINDOW_DAYS = 30
+RETIRE_AFTER = 15
+MIN_GAIN = 0.10
+HOOK_COMMAND = "agentplay autotune run --daily --quiet"
+LOG_MAX = 200
+
+
+def config(base: Path) -> dict[str, Any]:
+ try:
+ raw = json.loads((base / CONFIG).read_text(encoding="utf-8"))
+ except (OSError, ValueError):
+ raw = {}
+ raw = raw if isinstance(raw, dict) else {}
+ raw.setdefault("repos", {})
+ raw.setdefault("pending", [])
+ raw.setdefault("dismissed", [])
+ raw.setdefault("log", [])
+ raw.setdefault("when", "manual")
+ return raw
+
+
+def save(base: Path, cfg: dict[str, Any]) -> None:
+ cfg["log"] = cfg.get("log", [])[-LOG_MAX:]
+ fixes._write_json(base / CONFIG, cfg)
+
+
+def _now() -> str:
+ return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+
+def _log(cfg: dict[str, Any], kind: str, **kw: Any) -> None:
+ cfg["log"].append({"at": _now(), "kind": kind, **kw})
+
+
+def set_repo(base: Path, repo: str, *, enabled: bool | None = None, claude_md: str | None = None) -> dict[str, Any]:
+ cfg = config(base)
+ r = cfg["repos"].setdefault(repo, {"enabled": False, "claudeMd": "ask"})
+ if enabled is not None:
+ r["enabled"] = bool(enabled)
+ if claude_md in ("ask", "auto"):
+ r["claudeMd"] = claude_md
+ save(base, cfg)
+ return cfg
+
+
+# ------------------------------------------------------------------ sessions
+
+
+def root_rows(store: Any, *, since: str | None = None) -> list[dict[str, Any]]:
+ """Root sessions with their facts (computed from the map where the row predates them)."""
+ out = []
+ for r in store.rows():
+ if r.get("role") in ("subagent", "helper") or not r.get("calls"):
+ continue
+ if since and (r.get("sessionDate") or "") < since:
+ continue
+ f = r.get("facts") if r.get("factsVersion") == facts.FACTS_VERSION else None
+ if f is None:
+ doc = store.get(r["sessionId"])
+ f = facts.stamp(doc)["facts"] if doc is not None else None
+ if f is not None:
+ out.append({**r, "facts": f})
+ return out
+
+
+def metric(rows: list[dict[str, Any]], m: dict[str, Any] | None) -> float | None:
+ """A fix's own measure over ``rows``. Lower is better except ``verified_share``."""
+ if not m:
+ return None
+ name, verb = m.get("name"), m.get("verb")
+ if name == "verified_share":
+ edited = [r for r in rows if r["facts"].get("edited")]
+ return sum(bool(r["facts"].get("verifyAfterLastEdit")) for r in edited) / len(edited) if edited else None
+ cs = [r["facts"].get("cmd", {}).get(verb) for r in rows]
+ cs = [c for c in cs if c]
+ calls = sum(c.get("calls", 0) for c in cs)
+ if name == "fail_rate":
+ return sum(c.get("fails", 0) for c in cs) / calls if calls else None
+ if name == "out_bytes":
+ return sum(c.get("outBytes", 0) for c in cs) / calls if calls else None
+ if name == "denials":
+ return sum((c.get("byClass") or {}).get("permission_denied", 0) for c in cs) / len(rows) if rows else None
+ return None
+
+
+def _improved(name: str, before: float, after: float) -> bool:
+ if name == "verified_share":
+ return after >= before * (1 + MIN_GAIN) or after - before >= MIN_GAIN
+ return after <= before * (1 - MIN_GAIN)
+
+
+def effects(store: Any) -> list[dict[str, Any]]:
+ """Each active Autotune fix with its metric before and since."""
+ out = []
+ for e in fixes.active(store.base):
+ since = [r for r in root_rows(store, since=e["at"][:10]) if e["repo"] in (r.get("repos") or [])
+ and (r.get("startedAt") or "") >= e["at"]]
+ out.append({**e, "sessionsSince": len(since), "current": metric(since, e.get("metric"))})
+ return out
+
+
+# ------------------------------------------------------------------ run
+
+
+def run(store: Any, *, force: bool = False, today: str | None = None) -> dict[str, Any]:
+ base = store.base
+ cfg = config(base)
+ today = today or datetime.now(UTC).strftime("%Y-%m-%d")
+ if not force and (cfg.get("lastRun") or "")[:10] == today:
+ return {"skipped": "already ran today", "applied": [], "queued": [], "retired": []}
+ granted = fixes.grants(base)
+ enabled = {n for n, r in cfg["repos"].items() if r.get("enabled") and n in granted}
+ since = (datetime.now(UTC) - timedelta(days=WINDOW_DAYS)).strftime("%Y-%m-%d")
+ rows = root_rows(store, since=since)
+ done = {e["fixId"] for e in fixes.active(base)}
+ queued = {p["fixId"] for p in cfg["pending"]}
+ summary: dict[str, list[Any]] = {"applied": [], "queued": [], "retired": []}
+
+ for fx in health.fixes(rows):
+ if fx["repo"] not in enabled or fx["id"] in done or fx["id"] in queued or fx["id"] in cfg["dismissed"]:
+ continue
+ md = next((a for a in fx["actions"] if a["kind"] == "claude_md"), None)
+ repo_rows = [r for r in rows if fx["repo"] in (r.get("repos") or [])]
+ if md:
+ # Personal by default; the shared file only when the person said so for this repo.
+ rel = "CLAUDE.md" if cfg["repos"][fx["repo"]].get("claudeMd") == "auto" else "CLAUDE.local.md"
+ try:
+ entry = fixes.apply(base, fx, md, rel=rel, source="autotune",
+ baseline=metric(repo_rows, fx.get("metric")))
+ except fixes.FixError as exc:
+ _log(cfg, "error", title=fx["title"], repo=fx["repo"], detail=exc.message)
+ continue
+ _log(cfg, "add", title=fx["title"], repo=fx["repo"], file=rel, entry=entry["id"])
+ summary["applied"].append(fx["title"])
+ continue
+ action = fx["actions"][0] if fx["actions"] else None
+ if action is None:
+ continue
+ cfg["pending"].append({"fixId": fx["id"], "fix": fx, "action": action, "at": _now(),
+ "baseline": metric(repo_rows, fx.get("metric"))})
+ _log(cfg, "queue", title=fx["title"], repo=fx["repo"], file=action.get("file"))
+ summary["queued"].append(fx["title"])
+
+ for e in effects(store):
+ if e.get("source") != "autotune" or e.get("baseline") is None or e.get("current") is None:
+ continue
+ if e["sessionsSince"] >= RETIRE_AFTER and not _improved(e["metric"]["name"], e["baseline"], e["current"]):
+ fixes.undo(base, e["id"], reason="no measurable effect")
+ _log(cfg, "retire", title=e["title"], repo=e["repo"], file=e["file"],
+ detail=f"no measurable change after {e['sessionsSince']} sessions")
+ summary["retired"].append(e["title"])
+
+ cfg["lastRun"] = _now()
+ save(base, cfg)
+ return summary
+
+
+def approve(store: Any, fix_id: str) -> dict[str, Any]:
+ cfg = config(store.base)
+ item = next((p for p in cfg["pending"] if p["fixId"] == fix_id), None)
+ if item is None:
+ raise fixes.FixError("not_found", "That fix is no longer waiting.")
+ entry = fixes.apply(store.base, item["fix"], item["action"], source="autotune", baseline=item.get("baseline"))
+ cfg["pending"] = [p for p in cfg["pending"] if p["fixId"] != fix_id]
+ _log(cfg, "approve", title=item["fix"]["title"], repo=item["fix"]["repo"], file=item["action"].get("file"),
+ entry=entry["id"])
+ save(store.base, cfg)
+ return entry
+
+
+def dismiss(store: Any, fix_id: str, *, forever: bool = False) -> None:
+ cfg = config(store.base)
+ cfg["pending"] = [p for p in cfg["pending"] if p["fixId"] != fix_id]
+ if forever and fix_id not in cfg["dismissed"]:
+ cfg["dismissed"].append(fix_id)
+ save(store.base, cfg)
+
+
+def status(store: Any) -> dict[str, Any]:
+ cfg = config(store.base)
+ return {
+ "when": cfg.get("when"),
+ "lastRun": cfg.get("lastRun"),
+ "hookInstalled": hook_installed(),
+ "repos": [
+ {**r, **cfg["repos"].get(r["name"], {"enabled": False, "claudeMd": "ask"})}
+ for r in fixes.status(store.base)["repos"]
+ ],
+ "pending": [{"fixId": p["fixId"], "title": p["fix"]["title"], "pattern": p["fix"]["pattern"],
+ "points": p["fix"]["points"], "repo": p["fix"]["repo"], "action": p["action"]} for p in cfg["pending"]],
+ "log": list(reversed(cfg["log"][-50:])),
+ "active": effects(store),
+ }
+
+
+# ------------------------------------------------------------------ SessionStart hook
+
+
+def _claude_settings() -> Path:
+ return Path.home() / ".claude" / "settings.json"
+
+
+def hook_installed() -> bool:
+ try:
+ data = json.loads(_claude_settings().read_text(encoding="utf-8"))
+ except (OSError, ValueError):
+ return False
+ groups = ((data.get("hooks") or {}).get("SessionStart") or []) if isinstance(data, dict) else []
+ return any(h.get("command") == HOOK_COMMAND for g in groups for h in g.get("hooks", []))
+
+
+def install_hook() -> Path:
+ """Add the daily run to Claude Code's user settings as a SessionStart hook (merged, idempotent)."""
+ path = _claude_settings()
+ try:
+ data = json.loads(path.read_text(encoding="utf-8")) if path.exists() else {}
+ except ValueError as exc:
+ raise fixes.FixError("bad_json", f"{path} is not valid JSON; fix it by hand first.") from exc
+ if not hook_installed():
+ data.setdefault("hooks", {}).setdefault("SessionStart", []).append(
+ {"hooks": [{"type": "command", "command": HOOK_COMMAND}]}
+ )
+ path.parent.mkdir(parents=True, exist_ok=True)
+ fixes._atomic_write(path, (json.dumps(data, indent=2) + "\n").encode("utf-8"))
+ return path
+
+
+def uninstall_hook() -> None:
+ path = _claude_settings()
+ try:
+ data = json.loads(path.read_text(encoding="utf-8"))
+ except (OSError, ValueError):
+ return
+ groups = (data.get("hooks") or {}).get("SessionStart") or []
+ kept = [g for g in groups if not any(h.get("command") == HOOK_COMMAND for h in g.get("hooks", []))]
+ if len(kept) != len(groups):
+ if kept:
+ data["hooks"]["SessionStart"] = kept
+ else:
+ del data["hooks"]["SessionStart"]
+ fixes._atomic_write(path, (json.dumps(data, indent=2) + "\n").encode("utf-8"))
diff --git a/python/src/agentplay/builder.py b/python/src/agentplay/builder.py
index 09ecd1a..942a461 100644
--- a/python/src/agentplay/builder.py
+++ b/python/src/agentplay/builder.py
@@ -195,6 +195,10 @@ class RepoResolver:
self._cache[k] = result
return result
+ def roots(self) -> dict[str, str]:
+ """Repo name -> checkout root for every repo resolved so far (local use only)."""
+ return {name: root for v in self._cache.values() if v for root, name, _ in [v]}
+
@staticmethod
def _remote(root: Path, git: Path) -> tuple[str, str]:
config_path = None
diff --git a/python/src/agentplay/cli.py b/python/src/agentplay/cli.py
index 45917f0..abc1153 100644
--- a/python/src/agentplay/cli.py
+++ b/python/src/agentplay/cli.py
@@ -1,4 +1,4 @@
-"""Command line: ``agentplay [view|build|list|export|import|agents]``.
+"""Command line: ``agentplay [view|build|list|export|import|agents|fix|repos|autotune]``.
Run with no arguments to build maps for your sessions and open the viewer.
"""
@@ -324,6 +324,123 @@ def cmd_agents(_args: argparse.Namespace) -> int:
# --------------------------------------------------------------------------- parser
+def _health_fixes(st: Store, days: int = 30) -> list[dict]:
+ from . import autotune, health
+
+ since = (datetime.now(UTC) - timedelta(days=days)).strftime("%Y-%m-%d")
+ return health.fixes(autotune.root_rows(st, since=since))
+
+
+def cmd_fix(args: argparse.Namespace) -> int:
+ from . import fixes
+
+ st = Store()
+ items = _health_fixes(st)
+ if args.action == "list":
+ if not items:
+ print("No fixes: nothing specific stands out in the last 30 days.")
+ applied = {e["fixId"] for e in fixes.active(st.base)}
+ for n, fx in enumerate(items, 1):
+ mark = " (applied)" if fx["id"] in applied else ""
+ pts = f"+{fx['points']:.1f} pts" if fx["points"] else " 0 pts"
+ print(f"{n:>2}. {pts} {fx['title']}{mark}")
+ print(f" {fx['pattern']}")
+ return 0
+ if args.action == "undo":
+ try:
+ entry = fixes.undo(st.base, args.target)
+ except fixes.FixError as exc:
+ print(f"agentplay: {exc.message}", file=sys.stderr)
+ return 1
+ print(f"Undid: {entry['title']} ({entry['repo']}, {entry['file']}).")
+ return 0
+ try:
+ fx = items[int(args.target) - 1]
+ except (ValueError, IndexError):
+ print("agentplay: give the number from `agentplay fix list`.", file=sys.stderr)
+ return 1
+ if not fx["actions"]:
+ print(f"agentplay: {fx['title']}: nothing to write; it names an integration to fix by hand.", file=sys.stderr)
+ return 1
+ action = fx["actions"][args.variant]
+ try:
+ entry = fixes.apply(st.base, fx, action, rel=args.to, source="cli")
+ except fixes.FixError as exc:
+ print(f"agentplay: {exc.message}", file=sys.stderr)
+ return 1
+ print(f"Wrote {entry['file']} in {entry['repo']}: {fx['title']}. Undo with `agentplay fix undo {entry['id']}`.")
+ return 0
+
+
+def cmd_repos(args: argparse.Namespace) -> int:
+ from . import fixes
+
+ st = Store()
+ try:
+ if args.action == "grant":
+ print(f"agentplay can now write fixes to {fixes.grant(st.base, args.repo, args.path)}.")
+ elif args.action == "revoke":
+ fixes.revoke(st.base, args.repo)
+ print(f"agentplay will no longer write to {args.repo}.")
+ else:
+ for r in fixes.status(st.base)["repos"]:
+ print(f"{'●' if r['granted'] else '○'} {r['name']} {r['root'] or '(no checkout on this machine)'}")
+ except fixes.FixError as exc:
+ print(f"agentplay: {exc.message}", file=sys.stderr)
+ return 1
+ return 0
+
+
+def cmd_autotune(args: argparse.Namespace) -> int:
+ from . import autotune, fixes
+
+ st = Store()
+ try:
+ if args.action == "on":
+ for repo in args.repo or [r["name"] for r in fixes.status(st.base)["repos"] if r["granted"]]:
+ autotune.set_repo(st.base, repo, enabled=True)
+ cfg = autotune.config(st.base)
+ if args.at:
+ cfg["when"] = args.at
+ autotune.save(st.base, cfg)
+ print(f"Add this to your crontab (crontab -e) to run daily at {args.at}:")
+ hh, mm = args.at.split(":")
+ print(f" {int(mm)} {int(hh)} * * * {autotune.HOOK_COMMAND}")
+ else:
+ path = autotune.install_hook()
+ cfg["when"] = "session-start"
+ autotune.save(st.base, cfg)
+ print(f"Autotune runs at most once a day, when a Claude Code session starts ({path}).")
+ elif args.action == "off":
+ for repo in args.repo or list(autotune.config(st.base)["repos"]):
+ autotune.set_repo(st.base, repo, enabled=False)
+ if not args.repo:
+ autotune.uninstall_hook()
+ print("Autotune is off.")
+ elif args.action == "run":
+ res = autotune.run(st, force=not args.daily)
+ if not args.quiet:
+ if res.get("skipped"):
+ print(f"Autotune: {res['skipped']}.")
+ for k in ("applied", "queued", "retired"):
+ for title in res[k]:
+ print(f"{k}: {title}")
+ elif args.action == "undo":
+ entry = fixes.undo(st.base, args.repo[0] if args.repo else "")
+ print(f"Undid: {entry['title']}.")
+ else:
+ s = autotune.status(st)
+ print(f"Runs: {s['when']}; last run {s['lastRun'] or 'never'}; hook {'installed' if s['hookInstalled'] else 'not installed'}.")
+ for r in s["repos"]:
+ print(f"{'●' if r.get('enabled') and r['granted'] else '○'} {r['name']}")
+ for p in s["pending"]:
+ print(f"waiting: {p['title']} ({p['repo']}) - approve it in the viewer")
+ except fixes.FixError as exc:
+ print(f"agentplay: {exc.message}", file=sys.stderr)
+ return 1
+ return 0
+
+
def _build_flags(p: argparse.ArgumentParser) -> None:
p.add_argument("--since", help="only sessions changed since (30d, 12h, 2w, YYYY-MM-DD)")
p.add_argument("--agents", help=f"comma-separated subset of: {', '.join(discover.AGENTS)}")
@@ -376,6 +493,27 @@ def parser() -> argparse.ArgumentParser:
a = sub.add_parser("agents", parents=[common], help="show which agents were found on this machine")
a.set_defaults(fn=cmd_agents)
+
+ fx = sub.add_parser("fix", parents=[common], help="list, apply or undo Run health fixes")
+ fx.add_argument("action", choices=["list", "apply", "undo"])
+ fx.add_argument("target", nargs="?", default="", help="fix number (apply) or entry id (undo)")
+ fx.add_argument("--variant", type=int, default=0, help="which of a fix's actions to apply (default: the first)")
+ fx.add_argument("--to", choices=["CLAUDE.md", "CLAUDE.local.md"], help="instruction file to write to")
+ fx.set_defaults(fn=cmd_fix)
+
+ rp = sub.add_parser("repos", parents=[common], help="choose which repos agentplay may write fixes to")
+ rp.add_argument("action", choices=["list", "grant", "revoke"], nargs="?", default="list")
+ rp.add_argument("repo", nargs="?", default="")
+ rp.add_argument("--path", help="the checkout to use (default: the one builds recorded)")
+ rp.set_defaults(fn=cmd_repos)
+
+ at = sub.add_parser("autotune", parents=[common], help="apply fixes daily and retire the ones that don't help")
+ at.add_argument("action", choices=["on", "off", "run", "status", "undo"], nargs="?", default="status")
+ at.add_argument("--repo", action="append", help="repo name (repeatable; default: every granted repo)")
+ at.add_argument("--at", help="run daily at HH:MM from cron instead of on session start")
+ at.add_argument("--daily", action="store_true", help="skip if it already ran today")
+ at.add_argument("--quiet", action="store_true")
+ at.set_defaults(fn=cmd_autotune)
return ap
diff --git a/python/src/agentplay/discover.py b/python/src/agentplay/discover.py
index d7cf7b3..e83dd18 100644
--- a/python/src/agentplay/discover.py
+++ b/python/src/agentplay/discover.py
@@ -244,7 +244,8 @@ class SkipSession(Exception):
def build_map(c: Candidate, source: Any, *, path_mode: str = "relative",
- hmac_key: bytes | None = None, version: str = "") -> dict[str, Any]:
+ hmac_key: bytes | None = None, version: str = "",
+ resolver: builder.RepoResolver | None = None) -> dict[str, Any]:
"""Build the ``agentplay/v1`` document for one candidate.
Claude Code is read straight from its JSONL (the only way to see subagent
@@ -258,7 +259,7 @@ def build_map(c: Candidate, source: Any, *, path_mode: str = "relative",
raise SkipSession("too_large")
if c.agent == "claude-code" and c.path.endswith(".jsonl"):
return builder.build_claude_code_map(
- Path(c.path), path_mode=path_mode, hmac_key=hmac_key, cli_version=version
+ Path(c.path), path_mode=path_mode, hmac_key=hmac_key, cli_version=version, resolver=resolver
)
spans = source.get_spans_by_session(c.session_id)
if not spans:
@@ -270,6 +271,7 @@ def build_map(c: Candidate, source: Any, *, path_mode: str = "relative",
path_mode=path_mode,
hmac_key=hmac_key,
cli_version=version,
+ resolver=resolver,
started_at_hint=c.mtime or None,
)
diff --git a/python/src/agentplay/facts.py b/python/src/agentplay/facts.py
index 6242863..66b55c5 100644
--- a/python/src/agentplay/facts.py
+++ b/python/src/agentplay/facts.py
@@ -18,7 +18,7 @@ from typing import Any
from .builder import _NON_CALL_KINDS, _error_source, estimate_cost_usd
-FACTS_VERSION = 1
+FACTS_VERSION = 2
# Outcomes whose whole cost counts as abandoned spend. `interrupted` is left
# out on purpose: stopping an agent is often the right call.
@@ -151,9 +151,12 @@ def compute(doc: dict[str, Any]) -> dict[str, Any]:
for e in evs:
if e["kind"] not in _COMMAND_KINDS:
continue
- verb = str(e.get("verb") or e.get("tool") or "?")[:60]
- c = cmd.setdefault(verb, {"calls": 0, "fails": 0, "retries": 0, "byClass": {}})
+ verb = command_label(e)
+ c = cmd.setdefault(verb, {"calls": 0, "fails": 0, "retries": 0, "byClass": {}, "verify": False, "outBytes": 0})
c["calls"] += 1
+ c["outBytes"] += int(e.get("outBytes") or 0)
+ if e["kind"] == "verify":
+ c["verify"] = True
if e.get("retryOf") is not None:
c["retries"] += 1
if e.get("err"):
@@ -181,6 +184,22 @@ def compute(doc: dict[str, Any]) -> dict[str, Any]:
cls = str(e.get("errClass") or "other")
classes[cls] = classes.get(cls, 0) + 1
+ mcp: dict[str, dict[str, int]] = {}
+ hooks: dict[str, int] = {}
+ subagents: dict[str, dict[str, int]] = {}
+ for e in evs:
+ if e["kind"] == "mcp":
+ m = mcp.setdefault(str(e.get("server") or "?")[:60], {"calls": 0, "fails": 0})
+ m["calls"] += 1
+ m["fails"] += int(bool(e.get("err")))
+ elif e.get("err") and _error_source(e) == "hook":
+ name = str(e.get("hook") or e.get("hookEvent") or "hook")[:60]
+ hooks[name] = hooks.get(name, 0) + 1
+ elif e["kind"] == "subagent":
+ sa = subagents.setdefault(str(e.get("subagentType") or "general")[:60], {"launches": 0, "noResult": 0})
+ sa["launches"] += 1
+ sa["noResult"] += int(bool(e.get("err")) and e.get("errClass") in _DEAD_LANE)
+
return {
"outcome": outcome,
"edited": bool(edits),
@@ -212,6 +231,63 @@ def compute(doc: dict[str, Any]) -> dict[str, Any]:
"stallMs": sum(int(e.get("ms") or 0) for e in evs if e["kind"] == "delay" and e.get("cause") == "stall"),
"firstPromptChars": int(users[0].get("chars") or 0) if users else 0,
"userTurns": len(users),
+ "mcp": mcp,
+ "hookFails": hooks,
+ "subagents": subagents,
+ **_explore(evs),
+ }
+
+
+def command_label(e: dict[str, Any]) -> str:
+ """The command a shell event ran, as its verb plus a git or gh action (``git push``, ``gh pr_create``).
+
+ Never arguments: the builder only stores the verb, and a VCS action is
+ a closed vocabulary.
+ """
+ verb = str(e.get("verb") or e.get("tool") or "?")
+ action = (e.get("vcs") or {}).get("action")
+ if action and str(action) not in verb:
+ verb = f"{verb} {action}"
+ return verb[:60]
+
+
+def _explore(evs: list[dict[str, Any]]) -> dict[str, Any]:
+ """Whether the agent read before it edited (main agent only)."""
+ read_first: set[int] = set()
+ edited: dict[int, int] = {}
+ blind = rework = 0
+ steps_to_edit: int | None = None
+ explore = act = 0
+ last_edit_seq: dict[int, int] = {}
+ main = [e for e in evs if e.get("agent") == "main" and e["kind"] not in _NON_CALL_KINDS]
+ for i, e in enumerate(main):
+ if e["kind"] in ("read", "search"):
+ explore += 1
+ elif e["kind"] in ("edit", "exec", "verify"):
+ act += 1
+ for t in e.get("targets") or []:
+ fid = t.get("file")
+ if not isinstance(fid, int):
+ continue
+ if t.get("touch") == "read":
+ read_first.add(fid)
+ elif t.get("touch") == "edit":
+ if steps_to_edit is None:
+ steps_to_edit = i
+ if fid not in edited and fid not in read_first and t.get("op") != "create":
+ blind += 1
+ prev = last_edit_seq.get(fid)
+ if e.get("err") or (prev is not None and i - prev <= 5):
+ rework += 1
+ edited[fid] = edited.get(fid, 0) + 1
+ last_edit_seq[fid] = i
+ return {
+ "explore": explore,
+ "act": act,
+ "editedFiles": len(edited),
+ "blindEdits": blind,
+ "reworkEdits": rework,
+ "stepsToFirstEdit": steps_to_edit,
}
diff --git a/python/src/agentplay/fixes.py b/python/src/agentplay/fixes.py
new file mode 100644
index 0000000..0186aad
--- /dev/null
+++ b/python/src/agentplay/fixes.py
@@ -0,0 +1,303 @@
+"""Writing fixes into a repo: the only place agentplay writes outside ``~/.agentplay``.
+
+Rules, all enforced here rather than by callers:
+
+* Only a repo the person granted (``grants.json``), at the root recorded for
+ it, and only when that root still holds ``.git``.
+* Only four files: ``CLAUDE.md``, ``CLAUDE.local.md``, ``.claude/settings.json``
+ and ``.claude/settings.local.json``, resolved inside the root (a symlink
+ that points elsewhere is refused).
+* Instructions go between ``<!-- agentplay:start -->`` and ``<!-- agentplay:end -->``
+ markers; text outside them is never touched. Settings are merged, never
+ overwritten, and a file that is not valid JSON is left alone.
+* Refused when the file changed since the preview (``expect_hash``).
+* Every write is journalled in ``applied.json`` so it can be undone.
+
+Fix text is built only from command verbs, repo-relative paths and counts
+(``health.py``), so a fix cannot carry redacted content into a repo.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import time
+import uuid
+from pathlib import Path
+from typing import Any
+
+from .store import _atomic_write
+
+ALLOWED_FILES = ("CLAUDE.md", "CLAUDE.local.md", ".claude/settings.json", ".claude/settings.local.json")
+START = "<!-- agentplay:start -->"
+END = "<!-- agentplay:end -->"
+HEADING = "## Notes from agentplay"
+
+
+class FixError(Exception):
+ """A write that was refused; ``code`` is what the API and CLI report."""
+
+ def __init__(self, code: str, message: str) -> None:
+ super().__init__(message)
+ self.code = code
+ self.message = message
+
+
+# ------------------------------------------------------------------ local files
+
+
+def _read_json(path: Path, default: Any) -> Any:
+ try:
+ return json.loads(path.read_text(encoding="utf-8"))
+ except (OSError, ValueError):
+ return default
+
+
+def _write_json(path: Path, value: Any) -> None:
+ _atomic_write(path, json.dumps(value, indent=1).encode("utf-8"))
+
+
+def known_roots(base: Path) -> dict[str, str]:
+ """Repo name -> the checkout most recently seen for it (``repos.json``, written by builds)."""
+ raw = _read_json(base / "repos.json", {})
+ return {str(k): str(v) for k, v in raw.items()} if isinstance(raw, dict) else {}
+
+
+def record_roots(base: Path, roots: dict[str, str]) -> None:
+ if not roots:
+ return
+ cur = known_roots(base)
+ if all(cur.get(k) == v for k, v in roots.items()):
+ return
+ cur.update(roots)
+ _write_json(base / "repos.json", cur)
+
+
+def grants(base: Path) -> dict[str, str]:
+ raw = _read_json(base / "grants.json", {})
+ return {str(k): str(v) for k, v in raw.items()} if isinstance(raw, dict) else {}
+
+
+def grant(base: Path, repo: str, root: str | None = None) -> str:
+ """Allow writes to ``repo``. Uses the root builds recorded unless ``root`` is given."""
+ path = root or known_roots(base).get(repo)
+ if not path:
+ raise FixError("no_root", f"agentplay has not seen a checkout of {repo} on this machine.")
+ resolved = Path(path).expanduser().resolve()
+ if not (resolved / ".git").exists():
+ raise FixError("not_a_repo", f"{resolved} is not a git checkout.")
+ g = grants(base)
+ g[repo] = str(resolved)
+ _write_json(base / "grants.json", g)
+ return str(resolved)
+
+
+def revoke(base: Path, repo: str) -> None:
+ g = grants(base)
+ if g.pop(repo, None) is not None:
+ _write_json(base / "grants.json", g)
+
+
+def journal(base: Path) -> list[dict[str, Any]]:
+ raw = _read_json(base / "applied.json", [])
+ return raw if isinstance(raw, list) else []
+
+
+def _save_journal(base: Path, entries: list[dict[str, Any]]) -> None:
+ _write_json(base / "applied.json", entries)
+
+
+def active(base: Path) -> list[dict[str, Any]]:
+ return [e for e in journal(base) if not e.get("undoneAt")]
+
+
+# ------------------------------------------------------------------ paths
+
+
+def _target(base: Path, repo: str, rel: str) -> Path:
+ if rel not in ALLOWED_FILES:
+ raise FixError("file_not_allowed", f"agentplay only writes {', '.join(ALLOWED_FILES)}.")
+ root_s = grants(base).get(repo)
+ if not root_s:
+ raise FixError("not_granted", f"Allow writes to {repo} first.")
+ root = Path(root_s).resolve()
+ if not (root / ".git").exists():
+ raise FixError("not_a_repo", f"{root} is no longer a git checkout.")
+ target = (root / rel).resolve()
+ if not target.is_relative_to(root):
+ raise FixError("outside_repo", f"{rel} points outside {root}.")
+ return target
+
+
+def file_hash(text: str | None) -> str:
+ return hashlib.sha256((text or "").encode("utf-8")).hexdigest()[:16]
+
+
+def current(base: Path, repo: str, rel: str) -> str | None:
+ try:
+ return _target(base, repo, rel).read_text(encoding="utf-8")
+ except FileNotFoundError:
+ return None
+
+
+# ------------------------------------------------------------------ edits
+
+
+def _marker(fix_id: str) -> str:
+ return f"<!-- agentplay:{fix_id} -->"
+
+
+def add_lines(text: str | None, fix_id: str, lines: list[str]) -> str:
+ """``text`` with ``lines`` added inside the managed block (created at the end if absent)."""
+ text = text or ""
+ tagged = [f"- {line} {_marker(fix_id)}" for line in lines]
+ if START in text and END in text and text.index(START) < text.index(END):
+ head, rest = text.split(START, 1)
+ block, tail = rest.split(END, 1)
+ kept = [ln for ln in block.strip("\n").split("\n") if ln.strip() and _marker(fix_id) not in ln]
+ return f"{head}{START}\n" + "\n".join(kept + tagged) + f"\n{END}{tail}"
+ sep = "" if not text or text.endswith("\n\n") else "\n" if text.endswith("\n") else "\n\n"
+ return f"{text}{sep}{HEADING}\n\n{START}\n" + "\n".join(tagged) + f"\n{END}\n"
+
+
+def remove_lines(text: str, fix_id: str) -> str:
+ return "\n".join(ln for ln in text.split("\n") if _marker(fix_id) not in ln)
+
+
+def _settings(text: str | None, rel: str) -> dict[str, Any]:
+ if not text:
+ return {}
+ try:
+ value = json.loads(text)
+ except ValueError as exc:
+ raise FixError("bad_json", f"{rel} is not valid JSON; fix it by hand first.") from exc
+ if not isinstance(value, dict):
+ raise FixError("bad_json", f"{rel} is not a JSON object.")
+ return value
+
+
+def _apply_text(action: dict[str, Any], text: str | None, fix_id: str, rel: str) -> str:
+ kind = action.get("kind")
+ if kind == "claude_md":
+ lines = [str(x) for x in action.get("lines") or [] if str(x).strip()]
+ if not lines:
+ raise FixError("empty_fix", "This fix has nothing to write.")
+ return add_lines(text, fix_id, lines)
+ data = _settings(text, rel)
+ if kind == "settings_allow":
+ allow = data.setdefault("permissions", {}).setdefault("allow", [])
+ entry = str(action.get("entry") or "")
+ if entry and entry not in allow:
+ allow.append(entry)
+ elif kind == "stop_hook":
+ stop = data.setdefault("hooks", {}).setdefault("Stop", [])
+ cmd = str(action.get("command") or "")
+ if not any(h.get("command") == cmd for g in stop for h in g.get("hooks", [])):
+ stop.append({"hooks": [{"type": "command", "command": cmd}]})
+ else:
+ raise FixError("unknown_action", "This fix cannot be written to a file.")
+ return json.dumps(data, indent=2) + "\n"
+
+
+def _undo_text(entry: dict[str, Any], text: str) -> str:
+ kind = entry["action"].get("kind")
+ if kind == "claude_md":
+ return remove_lines(text, entry["fixId"])
+ data = _settings(text, entry["file"])
+ if kind == "settings_allow":
+ allow = (data.get("permissions") or {}).get("allow") or []
+ if entry["action"].get("entry") in allow:
+ allow.remove(entry["action"]["entry"])
+ elif kind == "stop_hook":
+ stop = (data.get("hooks") or {}).get("Stop") or []
+ data["hooks"]["Stop"] = [
+ g for g in stop if not any(h.get("command") == entry["action"].get("command") for h in g.get("hooks", []))
+ ]
+ if not data["hooks"]["Stop"]:
+ del data["hooks"]["Stop"]
+ return json.dumps(data, indent=2) + "\n"
+
+
+def preview(base: Path, repo: str, fix: dict[str, Any], action: dict[str, Any], rel: str | None = None) -> dict[str, Any]:
+ """The file as it is and as it would be, without writing."""
+ rel = rel or str(action.get("file"))
+ before = current(base, repo, rel)
+ after = _apply_text(action, before, fix["id"], rel)
+ return {"file": rel, "hash": file_hash(before), "before": before or "", "after": after}
+
+
+def apply(
+ base: Path,
+ fix: dict[str, Any],
+ action: dict[str, Any],
+ *,
+ rel: str | None = None,
+ expect_hash: str | None = None,
+ source: str = "button",
+ baseline: Any = None,
+) -> dict[str, Any]:
+ """Write one action of ``fix`` into its repo and journal it. Returns the journal entry."""
+ repo = str(fix.get("repo") or "")
+ if not repo:
+ raise FixError("no_repo", "This fix names an integration, not a repo; there is nothing to write.")
+ rel = rel or str(action.get("file"))
+ if action.get("kind") == "claude_md" and rel not in ("CLAUDE.md", "CLAUDE.local.md"):
+ raise FixError("file_not_allowed", "Instructions go in CLAUDE.md or CLAUDE.local.md.")
+ if action.get("kind") in ("settings_allow", "stop_hook") and not rel.startswith(".claude/"):
+ raise FixError("file_not_allowed", "Settings go in .claude/settings.json or .claude/settings.local.json.")
+ target = _target(base, repo, rel)
+ before = target.read_text(encoding="utf-8") if target.exists() else None
+ if expect_hash is not None and expect_hash != file_hash(before):
+ raise FixError("changed", f"{rel} changed since the preview. Look again before applying.")
+ after = _apply_text(action, before, fix["id"], rel)
+ target.parent.mkdir(parents=True, exist_ok=True)
+ _atomic_write(target, after.encode("utf-8"))
+ entry = {
+ "id": uuid.uuid4().hex[:10],
+ "fixId": fix["id"],
+ "rule": fix.get("rule"),
+ "title": fix.get("title"),
+ "repo": repo,
+ "file": rel,
+ "action": action,
+ "source": source,
+ "metric": fix.get("metric"),
+ "baseline": baseline,
+ "at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+ }
+ entries = journal(base)
+ entries.append(entry)
+ _save_journal(base, entries)
+ return entry
+
+
+def undo(base: Path, entry_id: str, *, reason: str = "undone") -> dict[str, Any]:
+ entries = journal(base)
+ entry = next((e for e in entries if e.get("id") == entry_id and not e.get("undoneAt")), None)
+ if entry is None:
+ raise FixError("not_found", "Nothing to undo with that id.")
+ target = _target(base, entry["repo"], entry["file"])
+ if target.exists():
+ text = target.read_text(encoding="utf-8")
+ _atomic_write(target, _undo_text(entry, text).encode("utf-8"))
+ entry["undoneAt"] = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+ entry["undoReason"] = reason
+ _save_journal(base, entries)
+ return entry
+
+
+def status(base: Path) -> dict[str, Any]:
+ """Repos agentplay can write to, and what it has written."""
+ roots, g = known_roots(base), grants(base)
+ names = sorted(set(roots) | set(g))
+ return {
+ "repos": [{"name": n, "root": g.get(n) or roots.get(n), "granted": n in g} for n in names],
+ "applied": active(base),
+ }
+
+
+def home() -> Path:
+ from .store import root
+
+ return Path(os.environ.get("AGENTPLAY_HOME") or root())
diff --git a/python/src/agentplay/health.py b/python/src/agentplay/health.py
new file mode 100644
index 0000000..1bfd813
--- /dev/null
+++ b/python/src/agentplay/health.py
@@ -0,0 +1,414 @@
+"""Run health: a 0-100 score over a window of sessions, and the specific fixes that would raise it.
+
+Five components worth 20 points each, every one computed from session facts
+(``facts.py``) of root sessions:
+
+======================== ====================================================
+Shipping sessions that opened a PR / sessions with an edit
+Verification sessions verified after the last edit / with an edit
+Efficiency 0.5 x (1 - min(1, 4 x (errors + retries) / calls))
+ + 0.5 x cache hit rate
+Context hygiene 0.6 x (1 - share compacting)
+ + 0.4 x (1 - min(1, re-reads after compaction / reads))
+Environment health 1 - min(1, 10 x configuration errors / calls)
+======================== ====================================================
+
+A fix is only proposed when it can name the command, tool or server behind
+it, and its points are the score it would recover: the component recomputed
+with the pattern's effect removed (or raised to a target rate), minus now.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Iterable
+from dataclasses import dataclass, field, replace
+from typing import Any
+
+MIN_SESSIONS = 10
+CONFIG_CLASSES = frozenset({"permission_denied", "blocked", "not_found"})
+VERIFY_TARGET = 0.7
+
+# Commands with a known quieter form. Only these can get a "noisy output"
+# fix: without one, the fix would be advice, not an instruction.
+QUIET_FORMS = {
+ "pytest": "pytest -q",
+ "npm test": "npm test -- --silent",
+ "pnpm test": "pnpm test --silent",
+ "yarn test": "yarn test --silent",
+ "jest": "jest --silent",
+ "vitest": "vitest run --reporter=dot",
+ "pnpm vitest": "pnpm vitest run --reporter=dot",
+ "cargo test": "cargo test -q",
+ "go test": "go test ./... (without -v)",
+}
+NOISY_BYTES = 40_000 # about 10k tokens of output per run
+
+
+@dataclass
+class Totals:
+ """The sums every component is computed from."""
+
+ sessions: int = 0
+ edited: int = 0
+ opened: int = 0
+ verified: int = 0
+ calls: int = 0
+ errors: int = 0
+ retries: int = 0
+ tok_in: int = 0
+ tok_cw: int = 0
+ tok_cr: int = 0
+ compacting: int = 0
+ reads: int = 0
+ rereads_ac: int = 0
+ config_errors: int = 0
+ extra: dict[str, Any] = field(default_factory=dict)
+
+
+def _config_errors(f: dict[str, Any]) -> int:
+ n = 0
+ for src, classes in (f.get("errorsBySource") or {}).items():
+ for cls, k in classes.items():
+ if src in ("hook", "mcp") or cls in CONFIG_CLASSES:
+ n += int(k)
+ return n
+
+
+def totals(rows: Iterable[dict[str, Any]]) -> Totals:
+ t = Totals()
+ for r in rows:
+ f = r.get("facts") or {}
+ t.sessions += 1
+ if f.get("edited"):
+ t.edited += 1
+ t.opened += int(f.get("prsCreated", 0) > 0)
+ t.verified += int(bool(f.get("verifyAfterLastEdit")))
+ t.calls += int(f.get("calls") or 0)
+ t.errors += int(f.get("errors") or 0)
+ t.retries += int(f.get("retries") or 0)
+ if f.get("hasCost"):
+ tok = f.get("tokens") or {}
+ t.tok_in += int(tok.get("in") or 0)
+ t.tok_cw += int(tok.get("cw") or 0)
+ t.tok_cr += int(tok.get("cr") or 0)
+ t.compacting += int((f.get("compactions") or 0) > 0)
+ t.reads += sum(int(x.get("reads") or 0) for x in (f.get("files") or {}).values())
+ t.rereads_ac += int(f.get("rereadsAfterCompaction") or 0)
+ t.config_errors += _config_errors(f)
+ return t
+
+
+def _clamp(x: float) -> float:
+ return max(0.0, min(1.0, x))
+
+
+def components(t: Totals) -> dict[str, float | None]:
+ """Each component as a 0-1 value, or None when it has nothing to measure."""
+ err_part = 1 - min(1.0, 4 * (t.errors + t.retries) / t.calls) if t.calls else None
+ tok = t.tok_in + t.tok_cw + t.tok_cr
+ cache = t.tok_cr / tok if tok else None
+ if err_part is None:
+ eff = None
+ elif cache is None:
+ eff = err_part # no cost data (Cursor only): missing data is neutral
+ else:
+ eff = 0.5 * err_part + 0.5 * cache
+ return {
+ "shipping": t.opened / t.edited if t.edited else None,
+ "verification": t.verified / t.edited if t.edited else None,
+ "efficiency": _clamp(eff) if eff is not None else None,
+ "context": _clamp(
+ 0.6 * (1 - t.compacting / t.sessions) + 0.4 * (1 - min(1.0, t.rereads_ac / t.reads if t.reads else 0.0))
+ ) if t.sessions else None,
+ "environment": _clamp(1 - min(1.0, 10 * t.config_errors / t.calls)) if t.calls else None,
+ }
+
+
+def score(t: Totals) -> float | None:
+ c = components(t)
+ if t.sessions < MIN_SESSIONS:
+ return None
+ # A component with nothing to measure counts in full: it can't be fixed.
+ return round(sum(20 * (v if v is not None else 1.0) for v in c.values()), 1)
+
+
+def _points(base: Totals, changed: Totals, key: str) -> float:
+ a, b = components(base)[key], components(changed)[key]
+ if a is None or b is None:
+ return 0.0
+ return round(max(0.0, 20 * (b - a)), 1)
+
+
+NAMES = {
+ "shipping": "Shipping",
+ "verification": "Verification",
+ "efficiency": "Efficiency",
+ "context": "Context hygiene",
+ "environment": "Environment health",
+}
+
+
+# ------------------------------------------------------------------ fixes
+
+
+def fix_id(rule: str, repo: str, subject: str) -> str:
+ return hashlib.sha256(f"{rule}\0{repo}\0{subject}".encode()).hexdigest()[:12]
+
+
+def _by_repo(rows: list[dict[str, Any]]) -> dict[str, list[dict[str, Any]]]:
+ out: dict[str, list[dict[str, Any]]] = {}
+ for r in rows:
+ repos = r.get("repos") or []
+ if repos:
+ out.setdefault(str(repos[0]), []).append(r)
+ return out
+
+
+def _cmds(rows: list[dict[str, Any]]) -> dict[str, dict[str, Any]]:
+ out: dict[str, dict[str, Any]] = {}
+ for r in rows:
+ for verb, c in ((r.get("facts") or {}).get("cmd") or {}).items():
+ a = out.setdefault(verb, {"calls": 0, "fails": 0, "retries": 0, "outBytes": 0, "verify": False,
+ "denied": 0, "deniedSessions": 0, "sessions": []})
+ a["calls"] += int(c.get("calls") or 0)
+ a["fails"] += int(c.get("fails") or 0)
+ a["retries"] += int(c.get("retries") or 0)
+ a["outBytes"] += int(c.get("outBytes") or 0)
+ a["verify"] = a["verify"] or bool(c.get("verify"))
+ denied = int((c.get("byClass") or {}).get("permission_denied", 0)) + int((c.get("byClass") or {}).get("blocked", 0))
+ a["denied"] += denied
+ a["deniedSessions"] += int(denied > 0)
+ a["sessions"].append(r.get("sessionId"))
+ return out
+
+
+def _fix(rule: str, repo: str, subject: str, component: str, title: str, pattern: str, effect: str,
+ points: float, sessions: list[str], actions: list[dict[str, Any]], metric: dict[str, Any] | None = None) -> dict[str, Any]:
+ return {
+ "id": fix_id(rule, repo, subject),
+ "rule": rule,
+ "repo": repo,
+ "subject": subject,
+ "component": component,
+ "title": title,
+ "pattern": pattern,
+ "effect": effect,
+ "points": points,
+ "sessions": [s for s in sessions if s][:50],
+ "actions": actions,
+ "metric": metric,
+ }
+
+
+def fixes(rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
+ """Specific fixes for the sessions in ``rows``, highest points first."""
+ base = totals(rows)
+ out: list[dict[str, Any]] = []
+ for repo, rrows in _by_repo(rows).items():
+ cmds = _cmds(rrows)
+ rt = totals(rrows)
+
+ # Verification: name the commands that already pass here.
+ if rt.edited >= 5 and rt.verified / rt.edited < 1 - 0.3:
+ passing = sorted(
+ (v for v, c in cmds.items() if c["verify"] and c["calls"] >= 3 and 1 - c["fails"] / c["calls"] >= 0.6),
+ key=lambda v: -cmds[v]["calls"],
+ )[:2]
+ if passing:
+ gain = max(0.0, VERIFY_TARGET * rt.edited - rt.verified)
+ changed = replace(base, verified=min(base.edited, base.verified + round(gain)))
+ unverified = [r["sessionId"] for r in rrows
+ if (r.get("facts") or {}).get("edited") and not (r.get("facts") or {}).get("verifyAfterLastEdit")]
+ rates = ", ".join(f"`{v}` passes {round(100 * (1 - cmds[v]['fails'] / cmds[v]['calls']))}% of runs" for v in passing)
+ joined = " && ".join(passing)
+ out.append(_fix(
+ "verify_before_stop", repo, joined, "verification",
+ "Run the passing checks before the agent stops",
+ f"{rt.edited - rt.verified} of {rt.edited} sessions with edits ended without a check after the last edit. Here {rates}.",
+ f"Sessions verified after the last edit rise from {round(100 * rt.verified / rt.edited)}% toward {round(100 * VERIFY_TARGET)}%.",
+ _points(base, changed, "verification"), unverified,
+ [
+ {"kind": "stop_hook", "label": "Add Stop hook", "file": ".claude/settings.json", "command": joined},
+ {"kind": "claude_md", "label": "Add to CLAUDE.md instead", "file": "CLAUDE.md",
+ "lines": [f"Before reporting done, run {' and '.join(f'`{v}`' for v in passing)}; they must pass."]},
+ ],
+ {"name": "verified_share"},
+ ))
+
+ # Efficiency: a failing command whose sibling passes.
+ for bad, c in cmds.items():
+ if c["fails"] < 5 or c["fails"] / c["calls"] < 0.4:
+ continue
+ family = bad.split()[0]
+ good = sorted(
+ (v for v, g in cmds.items() if v != bad and v.split()[0] == family and g["calls"] >= 3
+ and 1 - g["fails"] / g["calls"] >= 0.8),
+ key=lambda v: -cmds[v]["calls"],
+ )
+ if not good:
+ continue
+ g = cmds[good[0]]
+ changed = replace(base, errors=max(0, base.errors - c["fails"]), retries=max(0, base.retries - c["retries"]))
+ out.append(_fix(
+ "use_working_command", repo, bad, "efficiency",
+ f"Use `{good[0]}` instead of `{bad}`",
+ f"`{bad}` failed {c['fails']} of {c['calls']} runs here; `{good[0]}` passed {g['calls'] - g['fails']} of {g['calls']}.",
+ f"About {c['fails']} fewer failed runs and {c['retries']} fewer retries over the same number of sessions.",
+ _points(base, changed, "efficiency"), c["sessions"],
+ [{"kind": "claude_md", "label": "Add to CLAUDE.md", "file": "CLAUDE.md",
+ "lines": [f"Run `{good[0]}`, not `{bad}`: `{bad}` fails in this repo."]}],
+ {"name": "fail_rate", "verb": bad},
+ ))
+
+ # Context: output large enough to fill context, with a known quieter form.
+ for verb, c in cmds.items():
+ quiet = QUIET_FORMS.get(verb)
+ if not quiet or c["calls"] < 10 or c["outBytes"] / c["calls"] < NOISY_BYTES:
+ continue
+ ktok = round(c["outBytes"] / c["calls"] / 4 / 1000)
+ out.append(_fix(
+ "quiet_output", repo, verb, "context",
+ f"Run `{quiet}` so test output stops filling context",
+ f"`{verb}` output averaged about {ktok}k tokens per run across {c['calls']} runs.",
+ f"Most of those {ktok}k tokens per run stay out of context, so sessions compact less often.",
+ 0.0, c["sessions"],
+ [{"kind": "claude_md", "label": "Add to CLAUDE.md", "file": "CLAUDE.md",
+ "lines": [f"Run tests as `{quiet}`; rerun only a failing test for detail."]}],
+ {"name": "out_bytes", "verb": verb},
+ ))
+
+ # Environment: the same command refused in several sessions.
+ for verb, c in cmds.items():
+ if c["deniedSessions"] < 3 or "_" in verb:
+ continue
+ changed = replace(base, config_errors=max(0, base.config_errors - c["denied"]))
+ out.append(_fix(
+ "allow_command", repo, verb, "environment",
+ f"Allow `{verb}` in {repo}",
+ f"`{verb}` was refused {c['denied']} times in {c['deniedSessions']} sessions, each a stop for your approval.",
+ f"No permission stops on `{verb}` in {repo}.",
+ _points(base, changed, "environment"), c["sessions"],
+ [{"kind": "settings_allow", "label": "Add to settings.local.json", "file": ".claude/settings.local.json",
+ "entry": f"Bash({verb}:*)"}],
+ {"name": "denials", "verb": verb},
+ ))
+
+ # Store-wide: integrations that fail. No file can fix these, so the fix names them.
+ mcp: dict[str, dict[str, Any]] = {}
+ hooks: dict[str, dict[str, Any]] = {}
+ subs: dict[str, dict[str, Any]] = {}
+ for r in rows:
+ f = r.get("facts") or {}
+ for name, m in (f.get("mcp") or {}).items():
+ a = mcp.setdefault(name, {"calls": 0, "fails": 0, "sessions": []})
+ a["calls"] += m.get("calls", 0)
+ a["fails"] += m.get("fails", 0)
+ if m.get("fails"):
+ a["sessions"].append(r.get("sessionId"))
+ for name, n in (f.get("hookFails") or {}).items():
+ a = hooks.setdefault(name, {"fails": 0, "sessions": []})
+ a["fails"] += n
+ a["sessions"].append(r.get("sessionId"))
+ for name, s in (f.get("subagents") or {}).items():
+ a = subs.setdefault(name, {"launches": 0, "noResult": 0, "sessions": []})
+ a["launches"] += s.get("launches", 0)
+ a["noResult"] += s.get("noResult", 0)
+ if s.get("noResult"):
+ a["sessions"].append(r.get("sessionId"))
+ for name, m in mcp.items():
+ if m["calls"] >= 10 and m["fails"] / m["calls"] > 0.2:
+ changed = replace(base, config_errors=max(0, base.config_errors - m["fails"]))
+ out.append(_fix(
+ "broken_mcp", "", name, "environment",
+ f"Fix or remove the `{name}` MCP server",
+ f"`{name}` failed {m['fails']} of {m['calls']} calls ({round(100 * m['fails'] / m['calls'])}%).",
+ "Agents stop spending turns on a server that errors.",
+ _points(base, changed, "environment"), m["sessions"], [],
+ ))
+ for name, h in hooks.items():
+ if h["fails"] >= 5:
+ changed = replace(base, config_errors=max(0, base.config_errors - h["fails"]))
+ out.append(_fix(
+ "broken_hook", "", name, "environment",
+ f"Fix the `{name}` hook",
+ f"`{name}` failed {h['fails']} times in {len(h['sessions'])} sessions.",
+ "Tool calls stop being blocked by a failing hook.",
+ _points(base, changed, "environment"), h["sessions"], [],
+ ))
+ for name, s in subs.items():
+ if s["launches"] >= 5 and s["noResult"] / s["launches"] > 0.3:
+ out.append(_fix(
+ "dead_subagent", "", name, "efficiency",
+ f"Narrow or stop using the `{name}` subagent",
+ f"`{name}` ended with no result in {s['noResult']} of {s['launches']} launches.",
+ "Less spend on subagents that return nothing.",
+ 0.0, s["sessions"], [],
+ ))
+ out.sort(key=lambda x: (-x["points"], x["title"]))
+ return out
+
+
+# ------------------------------------------------------------------ report
+
+
+def _worst(rows: list[dict[str, Any]], key: str) -> list[dict[str, Any]]:
+ def why(f: dict[str, Any]) -> tuple[float, str] | None:
+ if key == "shipping" and f.get("edited") and not f.get("prsCreated"):
+ return f.get("costUsd", 0), "edited code, no PR"
+ if key == "verification" and f.get("edited") and not f.get("verifyAfterLastEdit"):
+ return f.get("costUsd", 0), "no check after the last edit"
+ if key == "efficiency" and (f.get("errors", 0) + f.get("retries", 0)):
+ n = f.get("errors", 0) + f.get("retries", 0)
+ return n, f"{n} failed calls and retries"
+ if key == "context" and f.get("compactions"):
+ return f["compactions"], f"{f['compactions']} compactions"
+ if key == "environment":
+ n = _config_errors(f)
+ if n:
+ return n, f"{n} configuration errors"
+ return None
+
+ scored = []
+ for r in rows:
+ w = why(r.get("facts") or {})
+ if w:
+ scored.append((w[0], r.get("sessionId"), w[1]))
+ scored.sort(key=lambda x: -x[0])
+ return [{"sessionId": sid, "why": text} for _, sid, text in scored[:3]]
+
+
+def report(rows: list[dict[str, Any]], prev_rows: list[dict[str, Any]] | None = None) -> dict[str, Any]:
+ """Everything the Run health page shows, for root sessions in a window."""
+ t = totals(rows)
+ comps = components(t)
+ prev = components(totals(prev_rows)) if prev_rows else {}
+ tok = t.tok_in + t.tok_cw + t.tok_cr
+ inputs = {
+ "shipping": [["Sessions with edits", t.edited], ["Opened a PR", t.opened]],
+ "verification": [["Sessions with edits", t.edited], ["Verified after last edit", t.verified]],
+ "efficiency": [["Errors + retries", t.errors + t.retries], ["Calls", t.calls],
+ ["Cache hit rate", f"{round(100 * t.tok_cr / tok)}%" if tok else "n/a"]],
+ "context": [["Sessions compacting", t.compacting], ["Re-reads after compaction", t.rereads_ac], ["Reads", t.reads]],
+ "environment": [["Configuration errors", t.config_errors], ["Calls", t.calls]],
+ }
+ prev_score = score(totals(prev_rows)) if prev_rows else None
+ return {
+ "sessions": t.sessions,
+ "minSessions": MIN_SESSIONS,
+ "score": score(t),
+ "prevScore": prev_score,
+ "components": [
+ {
+ "key": k,
+ "name": NAMES[k],
+ "value": comps[k],
+ "points": round(20 * comps[k], 1) if comps[k] is not None else None,
+ "prevPoints": round(20 * prev[k], 1) if prev.get(k) is not None else None,
+ "inputs": inputs[k],
+ "worst": _worst(rows, k),
+ }
+ for k in NAMES
+ ],
+ "fixes": fixes(rows),
+ }
diff --git a/python/src/agentplay/pipeline.py b/python/src/agentplay/pipeline.py
index 4eb7369..57a0c91 100644
--- a/python/src/agentplay/pipeline.py
+++ b/python/src/agentplay/pipeline.py
@@ -11,7 +11,7 @@ from dataclasses import dataclass, field
from datetime import UTC, datetime
from typing import Any
-from . import __version__, builder, discover, facts
+from . import __version__, builder, discover, facts, fixes, search
from .store import Store
logger = logging.getLogger("agentplay.pipeline")
@@ -204,6 +204,9 @@ def build_all(
# first scan can take minutes, so the open viewer fills in as maps land.
last_save = time.monotonic()
pending = False
+ # Shared across builds, so each checkout is resolved once and its root can
+ # be recorded (locally, in repos.json) for writing fixes later.
+ resolver = builder.RepoResolver()
for i, c in enumerate(cands):
if pending and time.monotonic() - last_save >= SAVE_EVERY_S:
store.save_index()
@@ -217,7 +220,8 @@ def build_all(
pending = True
continue
try:
- doc = discover.build_map(c, source, path_mode=path_mode, hmac_key=hmac_key, version=__version__)
+ doc = discover.build_map(c, source, path_mode=path_mode, hmac_key=hmac_key, version=__version__,
+ resolver=resolver)
except discover.SkipSession as exc:
report.skip(str(exc))
continue
@@ -237,6 +241,13 @@ def build_all(
report.built += 1
report.by_agent[c.agent] += 1
store.save_index()
+ try:
+ # Only names a stored map uses: a checkout merely passed on the way is not recorded.
+ used = {n for r in store.index.values() for n in r.get("repos") or []}
+ fixes.record_roots(store.base, {n: p for n, p in resolver.roots().items() if n in used})
+ search.refresh(store)
+ except OSError as exc: # the index is what matters; search catches up next run
+ report.errors.append(f"search index: {exc}")
if progress:
progress(len(cands), len(cands), "")
report.seconds = round(time.monotonic() - t0, 2)
diff --git a/python/src/agentplay/search.py b/python/src/agentplay/search.py
new file mode 100644
index 0000000..e53932f
--- /dev/null
+++ b/python/src/agentplay/search.py
@@ -0,0 +1,212 @@
+"""Search across every stored map: which sessions touched a file, command, MCP server and so on.
+
+Each map yields postings (``term -> [[seq, touch], ...]``) built only from
+fields the map already holds: repo-relative paths, command verbs, MCP server
+and tool names, skill and subagent types, models, repos, web hosts and error
+classes. Command arguments, prompt and output text are never stored, so they
+can never be searched.
+
+Postings live in ``~/.agentplay/search.json`` beside the index, rebuilt for a
+session whenever its map's content hash changes.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Iterable
+from typing import Any
+
+from .facts import command_label
+
+SEARCH_VERSION = 1
+FACETS = ("file", "cmd", "mcp", "skill", "subagent", "model", "repo", "host", "err")
+# Postings kept per term per session: enough to step through, small enough to load.
+MAX_SEQS = 40
+_FACET_RE = re.compile(rf"^({'|'.join(FACETS)}):(.+)$", re.I)
+
+TOUCHES = ("hit", "read", "edit", "fail")
+
+
+def postings(doc: dict[str, Any]) -> dict[str, list[list[Any]]]:
+ """``term -> [[seq, touch], ...]`` for one map. Session-level terms carry seq None."""
+ out: dict[str, list[list[Any]]] = {}
+ files = {f.get("id"): f for f in doc.get("files") or []}
+ repos = {r.get("id"): r.get("name") for r in doc.get("repos") or []}
+
+ def add(term: str, seq: int | None, touch: str) -> None:
+ lst = out.setdefault(term.lower(), [])
+ if len(lst) < MAX_SEQS:
+ lst.append([seq, touch])
+
+ for e in doc.get("events") or []:
+ seq = e.get("seq")
+ failed = bool(e.get("err"))
+ kind = e.get("kind")
+ for t in e.get("targets") or []:
+ f = files.get(t.get("file"))
+ if not f or not f.get("path"):
+ continue
+ touch = "fail" if failed else str(t.get("touch") or "hit")
+ path = str(f["path"])
+ add(f"file:{repos.get(f.get('repo'), '')}:{path}", seq, touch)
+ base = path.rsplit("/", 1)[-1]
+ if base != path:
+ add(f"file:{base}", seq, touch)
+ if kind in ("exec", "verify"):
+ add(f"cmd:{command_label(e)}", seq, "fail" if failed else "read")
+ elif kind == "mcp" and e.get("server"):
+ add(f"mcp:{e['server']}", seq, "fail" if failed else "read")
+ if e.get("tool"):
+ add(f"mcp:{e['server']}/{e['tool']}", seq, "fail" if failed else "read")
+ if e.get("skill"):
+ add(f"skill:{e['skill']}", seq, "fail" if failed else "read")
+ if kind == "subagent" and e.get("subagentType"):
+ add(f"subagent:{e['subagentType']}", seq, "fail" if failed else "read")
+ if e.get("host"):
+ add(f"host:{e['host']}", seq, "fail" if failed else "read")
+ if failed and e.get("errClass"):
+ add(f"err:{e['errClass']}", seq, "fail")
+ for m in (doc.get("session") or {}).get("models") or []:
+ add(f"model:{m}", None, "hit")
+ for name in repos.values():
+ if name:
+ add(f"repo:{name}", None, "hit")
+ return out
+
+
+# ------------------------------------------------------------------ the index file
+
+
+def load(path: Any) -> dict[str, Any]:
+ try:
+ raw = json.loads(path.read_text(encoding="utf-8"))
+ except (OSError, ValueError):
+ return {}
+ if not isinstance(raw, dict) or raw.get("version") != SEARCH_VERSION:
+ return {}
+ sessions = raw.get("sessions")
+ return sessions if isinstance(sessions, dict) else {}
+
+
+def dump(sessions: dict[str, Any]) -> bytes:
+ return json.dumps({"version": SEARCH_VERSION, "sessions": sessions}, separators=(",", ":")).encode("utf-8")
+
+
+def refresh(store: Any) -> int:
+ """Bring ``search.json`` up to date with the store. Returns how many sessions were (re)indexed.
+
+ Reads a map only when its content hash changed since it was indexed, so a
+ run with nothing new reads none.
+ """
+ from .store import _atomic_write
+
+ path = store.base / "search.json"
+ old = load(path)
+ out: dict[str, Any] = {}
+ n = 0
+ for sid, row in store.index.items():
+ h = str(row.get("contentHash") or "")
+ prev = old.get(sid)
+ if isinstance(prev, dict) and prev.get("hash") == h:
+ out[sid] = prev
+ continue
+ doc = store.get(sid)
+ if doc is None:
+ continue
+ try:
+ out[sid] = {"hash": h, "terms": postings(doc)}
+ except (KeyError, TypeError, ValueError, AttributeError):
+ continue
+ n += 1
+ if n or len(out) != len(old):
+ _atomic_write(path, dump(out))
+ return n
+
+
+# ------------------------------------------------------------------ querying
+
+
+def parse(q: str) -> tuple[str | None, str]:
+ """``file:auth.ts`` -> (``file``, ``auth.ts``); a bare query matches every facet."""
+ q = q.strip()
+ m = _FACET_RE.match(q)
+ if m:
+ return m.group(1).lower(), m.group(2).strip().lower()
+ return None, q.lower()
+
+
+def _matches(term: str, facet: str | None, value: str) -> bool:
+ f, _, v = term.partition(":")
+ if facet and f != facet:
+ return False
+ if f == "file":
+ # The full key is `file:<repo>:<path>`; match on the path, any repo.
+ v = v.split(":", 1)[-1] if v.count(":") else v
+ return value in v
+
+
+_VERBS = {"hit": "found", "read": "read", "edit": "edited", "fail": "failed"}
+
+
+def _label(term: str) -> str:
+ f, _, v = term.partition(":")
+ if f == "file":
+ v = v.split(":", 1)[-1].rsplit("/", 1)[-1]
+ return v
+
+
+def query(terms_by_session: dict[str, dict[str, list[list[Any]]]], q: str) -> dict[str, dict[str, Any]]:
+ """Sessions matching ``q``: ``sid -> {count, seqs, chips}``.
+
+ ``chips`` summarise the matches a person reads first ("edited auth.ts 3×"),
+ each with the first matching ``seq`` to open the session at.
+ """
+ facet, value = parse(q)
+ if not value:
+ return {}
+ out: dict[str, dict[str, Any]] = {}
+ for sid, terms in terms_by_session.items():
+ hits = [(t, p) for t, ps in terms.items() if _matches(t, facet, value) for p in ps]
+ if not hits:
+ continue
+ seqs = sorted({p[0] for _, p in hits if p[0] is not None})
+ groups: dict[tuple[str, str], list[int | None]] = {}
+ for t, (seq, touch) in hits:
+ # The basename and the full-path term of one file are the same match.
+ key = (_label(t), touch)
+ if seq not in groups.setdefault(key, []):
+ groups[key].append(seq)
+ chips = sorted(
+ (
+ {
+ "label": f"{_VERBS.get(touch, touch)} {label}" + (f" {len(s)}×" if s[0] is not None else ""),
+ "touch": touch,
+ "seq": min((x for x in s if x is not None), default=None),
+ "n": len(s),
+ }
+ for (label, touch), s in groups.items()
+ ),
+ key=lambda c: (-TOUCHES.index(c["touch"]) if c["touch"] in TOUCHES else 0, -c["n"]),
+ )
+ out[sid] = {"count": len(seqs) or len(hits), "seqs": seqs[:MAX_SEQS], "chips": chips[:4]}
+ return out
+
+
+def argument_fallback(terms_by_session: dict[str, dict[str, list[list[Any]]]], q: str) -> tuple[str, dict[str, Any]] | None:
+ """A query that names command arguments (``pnpm test auth``) can't match: arguments
+ are never stored. Retry with the longest command prefix that does match."""
+ facet, value = parse(q)
+ if facet not in (None, "cmd"):
+ return None
+ words = value.split()
+ for n in range(len(words) - 1, 0, -1):
+ prefix = " ".join(words[:n])
+ hits = query(terms_by_session, f"cmd:{prefix}")
+ if hits:
+ return prefix, hits
+ return None
+
+
+def iter_terms(rows: Iterable[tuple[str, dict[str, Any]]]) -> dict[str, dict[str, list[list[Any]]]]:
+ return {sid: entry.get("terms") or {} for sid, entry in rows if isinstance(entry, dict)}
diff --git a/python/src/agentplay/server.py b/python/src/agentplay/server.py
index efe46c4..63984c8 100644
--- a/python/src/agentplay/server.py
+++ b/python/src/agentplay/server.py
@@ -4,7 +4,8 @@ Binds to 127.0.0.1 only. Serves the static viewer from the package's
``viewer/`` directory and these endpoints over the local store:
``GET /api/status`` ``{available, mapCount, latestSessionDate, scanning}``
-``GET /api/sessions`` paged session rows (``from``, ``to``, ``search``, ``pageSize``, ``cursor``)
+``GET /api/sessions`` paged session rows (``from``, ``to``, ``search``, ``pageSize``, ``cursor``);
+ ``search`` also matches files, commands, MCP servers and more (see ``search.py``)
``GET /api/map`` one entry per ``session_id`` param, each with a ``url``
``GET /api/map-doc?id=...`` the map document itself
``GET /api/stats`` session facts for the Insights view (``from``, ``to``: inclusive ``YYYY-MM-DD``)
@@ -12,14 +13,22 @@ Binds to 127.0.0.1 only. Serves the static viewer from the package's
``GET /api/prompt-images?id=...`` per-turn metadata for images pasted into Claude Code prompts (this machine only)
``GET /api/prompt-image?id=...&turn=...&i=...`` one such image, read from the transcript on demand (this machine only)
``GET /api/hook-detail?id=...&uuid=...`` the message and command of one hook failure, read from the transcript on demand (this machine only)
+``GET /api/health`` Run health score, components and fixes for a window (``from``, ``to``)
+``GET /api/fix-preview`` a fix's file before and after (``fix``, ``i``: action index, ``file``, ``from``, ``to``)
+``GET /api/autotune`` Autotune settings, repos, the approval queue and its log
``POST /api/account`` ``{"action": "signup", "email": ...}``, ``{"action": "skip"}``, ``{"action": "disconnect"}``
+``POST /api/fix`` ``{"action": "apply", "fix", "i", "file"?, "hash"?, "from"?, "to"?}``, ``{"action": "undo", "entry"}``
+``POST /api/repos`` ``{"action": "grant" | "revoke", "repo"}``
+``POST /api/autotune`` ``{"action": "enable" | "disable" | "shared" | "approve" | "dismiss" | "never" | "run", ...}``
Pasted images are read from the original transcript when asked for and never
stored in a map, the index or an export; see ``prompt_images.py``. Hook failure
messages and commands are read the same way; see ``hook_detail.py``.
-The only write is ``~/.agentplay/account.json``, and the only thing that can leave
-the machine is an email the user typed into the signup card.
+Writes stay under ``~/.agentplay`` except fixes, which ``fixes.py`` writes only
+into repos the person granted, only to four agent files, and journals for undo.
+The only thing that can leave the machine is an email the user typed into the
+signup card.
"""
from __future__ import annotations
@@ -39,7 +48,8 @@ from pathlib import Path
from typing import Any
from urllib.parse import parse_qs, quote, urlsplit
-from . import account, facts, hook_detail, prompt_images
+from . import account, autotune, facts, fixes, health, hook_detail, prompt_images
+from . import search as search_index
from .store import Store
MAX_PAGE = 200
@@ -199,11 +209,16 @@ class _Handler(BaseHTTPRequestHandler):
# can tell "no sessions yet" from "no sessions".
scanning: threading.Event | None = None
lock = threading.Lock()
+ write_lock = threading.Lock()
# Facts for rows written before facts existed (or by an older FACTS_VERSION),
# computed from the stored map on first read. Kept in memory, keyed by the
# map's content hash: the server never writes the index, which a background
# scan may be saving at the same moment. The next build persists them.
facts_cache: dict[tuple[str, str], dict[str, Any] | None] = {}
+ # search.json as last read (by mtime and size) and postings computed for
+ # sessions it does not cover yet. In memory only, like `facts_cache`.
+ search_file: tuple[Any, dict[str, Any]] = (None, {})
+ search_mem: dict[tuple[str, str], dict[str, Any]] = {}
def log_message(self, fmt: str, *args: Any) -> None: # quiet by default
return
@@ -320,6 +335,12 @@ class _Handler(BaseHTTPRequestHandler):
return self._map_doc(q)
if url.path == "/api/stats":
return self._stats(q)
+ if url.path == "/api/health":
+ return self._health(q)
+ if url.path == "/api/fix-preview":
+ return self._fix_preview(q)
+ if url.path == "/api/autotune":
+ return self._json({"success": True, **autotune.status(self.store)})
if url.path == "/api/prompt-images":
return self._prompt_images(q)
if url.path == "/api/prompt-image":
@@ -342,9 +363,9 @@ class _Handler(BaseHTTPRequestHandler):
def do_POST(self) -> None: # noqa: N802 - http.server naming
url = urlsplit(self.path)
- if url.path != "/api/account":
+ if url.path not in ("/api/account", "/api/fix", "/api/repos", "/api/autotune"):
return self._error(404, "not_found", "Unknown endpoint.")
- # The only write this server takes. A browser on another site can reach
+ # Every write this server takes. A browser on another site can reach
# 127.0.0.1, so: same machine, a local Origin and Host (no DNS rebinding),
# and a JSON body, which a cross-site form can't send without a preflight
# this server never answers.
@@ -364,6 +385,17 @@ class _Handler(BaseHTTPRequestHandler):
except ValueError:
return self._error(400, "invalid_input", "Bad request body.")
action = body.get("action") if isinstance(body, dict) else None
+ if url.path != "/api/account":
+ try:
+ # Its own lock: a write reads the index through `self.lock` itself.
+ with self.write_lock:
+ return self._write(url.path, str(action or ""), body)
+ except fixes.FixError as exc:
+ return self._error(409, exc.code, exc.message)
+ except BrokenPipeError:
+ return None
+ except Exception: # noqa: BLE001 - never leak a traceback to the page
+ return self._error(500, "internal_error", "Something went wrong writing that.")
try:
if action == "skip":
return self._json({"success": True, **account.skip()})
@@ -383,6 +415,99 @@ class _Handler(BaseHTTPRequestHandler):
except Exception: # noqa: BLE001 - never leak a traceback to the page
return self._error(500, "internal_error", "Something went wrong saving that.")
+ # ------------------------------------------------------------------ run health and fixes
+ def _window(self, lo: str, hi: str) -> list[dict[str, Any]]:
+ out = []
+ for r in self._rows():
+ day = r.get("sessionDate") or ""
+ if (lo and day < lo) or (hi and day and day > hi):
+ continue
+ with self.lock:
+ f = self._facts(r)
+ if f is not None:
+ out.append({**r, "facts": f})
+ return out
+
+ @staticmethod
+ def _prev_range(lo: str, hi: str) -> tuple[str, str] | None:
+ from datetime import date, timedelta
+ try:
+ a, b = date.fromisoformat(lo), date.fromisoformat(hi)
+ except ValueError:
+ return None
+ span = (b - a).days + 1
+ return (a - timedelta(days=span)).isoformat(), (a - timedelta(days=1)).isoformat()
+
+ def _health(self, q: dict[str, list[str]]) -> None:
+ lo, hi = (q.get("from") or [""])[0], (q.get("to") or [""])[0]
+ rows = self._window(lo, hi)
+ prev = self._prev_range(lo, hi)
+ report = health.report(rows, self._window(*prev) if prev else None)
+ ids = {w["sessionId"] for c in report["components"] for w in c["worst"]}
+ ids |= {sid for fx in report["fixes"] for sid in fx["sessions"][:5]}
+ titles = {r["sessionId"]: r.get("sessionTitle") for r in rows if r["sessionId"] in ids}
+ st = fixes.status(self.store.base)
+ self._json({"success": True, **report, "titles": titles, "repos": st["repos"],
+ "applied": [{"id": e["id"], "fixId": e["fixId"], "file": e["file"], "kind": e["action"].get("kind")}
+ for e in st["applied"]]})
+
+ def _find_fix(self, fix_id: str, lo: str, hi: str) -> dict[str, Any]:
+ fx = next((f for f in health.fixes(self._window(lo, hi)) if f["id"] == fix_id), None)
+ if fx is None:
+ raise fixes.FixError("not_found", "That fix no longer applies to these sessions.")
+ return fx
+
+ def _fix_preview(self, q: dict[str, list[str]]) -> None:
+ try:
+ fx = self._find_fix((q.get("fix") or [""])[0], (q.get("from") or [""])[0], (q.get("to") or [""])[0])
+ raw = (q.get("i") or ["0"])[0]
+ i = 0 if raw == "0" else _non_negative_int(raw)
+ if i is None or i >= len(fx["actions"]):
+ return self._error(400, "invalid_input", "No such action.")
+ rel = (q.get("file") or [None])[0]
+ self._json({"success": True, **fixes.preview(self.store.base, fx["repo"], fx, fx["actions"][i], rel)})
+ except fixes.FixError as exc:
+ self._error(409, exc.code, exc.message)
+
+ def _write(self, path: str, action: str, body: dict[str, Any]) -> None:
+ base = self.store.base
+ if path == "/api/repos":
+ repo = str(body.get("repo") or "")
+ if action == "grant":
+ return self._json({"success": True, "root": fixes.grant(base, repo)})
+ if action == "revoke":
+ fixes.revoke(base, repo)
+ return self._json({"success": True})
+ elif path == "/api/fix":
+ if action == "apply":
+ fx = self._find_fix(str(body.get("fix") or ""), str(body.get("from") or ""), str(body.get("to") or ""))
+ i = body.get("i", 0)
+ if not isinstance(i, int) or not 0 <= i < len(fx["actions"]):
+ return self._error(400, "invalid_input", "No such action.")
+ rel = body.get("file") if isinstance(body.get("file"), str) else None
+ expect = body.get("hash") if isinstance(body.get("hash"), str) else None
+ entry = fixes.apply(base, fx, fx["actions"][i], rel=rel, expect_hash=expect)
+ return self._json({"success": True, "entry": entry})
+ if action == "undo":
+ return self._json({"success": True, "entry": fixes.undo(base, str(body.get("entry") or ""))})
+ elif path == "/api/autotune":
+ repo = str(body.get("repo") or "")
+ fix_id = str(body.get("fixId") or "")
+ if action in ("enable", "disable"):
+ autotune.set_repo(base, repo, enabled=action == "enable")
+ elif action == "shared":
+ autotune.set_repo(base, repo, claude_md="auto" if body.get("value") else "ask")
+ elif action == "approve":
+ autotune.approve(self.store, fix_id)
+ elif action in ("dismiss", "never"):
+ autotune.dismiss(self.store, fix_id, forever=action == "never")
+ elif action == "run":
+ return self._json({"success": True, **autotune.run(self.store, force=True)})
+ else:
+ return self._error(400, "invalid_input", "Unknown action.")
+ return self._json({"success": True, **autotune.status(self.store)})
+ return self._error(400, "invalid_input", "Unknown action.")
+
def _rows(self) -> list[dict[str, Any]]:
with self.lock:
return [r for r in self.store.rows() if r.get("role") not in ("subagent", "helper") and r.get("calls")]
@@ -394,6 +519,35 @@ class _Handler(BaseHTTPRequestHandler):
self._json({"success": True, "available": bool(rows), "mapCount": len(rows), "latestSessionDate": latest,
"scanning": scanning})
+ def _search_terms(self, rows: list[dict[str, Any]]) -> dict[str, dict[str, Any]]:
+ path = self.store.base / "search.json"
+ try:
+ st = path.stat()
+ stamp: Any = (st.st_mtime_ns, st.st_size)
+ except OSError:
+ stamp = None
+ with self.lock:
+ if self.search_file[0] != stamp:
+ type(self).search_file = (stamp, search_index.load(path) if stamp else {})
+ indexed = self.search_file[1]
+ out: dict[str, dict[str, Any]] = {}
+ for r in rows:
+ sid = str(r.get("sessionId") or "")
+ h = str(r.get("contentHash") or "")
+ entry = indexed.get(sid)
+ if isinstance(entry, dict) and entry.get("hash") == h:
+ out[sid] = entry.get("terms") or {}
+ continue
+ key = (sid, h)
+ if key not in self.search_mem:
+ doc = self.store.get(sid)
+ try:
+ self.search_mem[key] = search_index.postings(doc) if doc is not None else {}
+ except (KeyError, TypeError, ValueError, AttributeError):
+ self.search_mem[key] = {}
+ out[sid] = self.search_mem[key]
+ return out
+
def _sessions(self, q: dict[str, list[str]]) -> None:
rows = self._rows()
lo = (q.get("from") or [""])[0]
@@ -403,21 +557,35 @@ class _Handler(BaseHTTPRequestHandler):
size = min(MAX_PAGE, max(1, int((q.get("pageSize") or [DEFAULT_PAGE])[0])))
except ValueError:
size = DEFAULT_PAGE
+ in_window = [
+ r for r in rows
+ if not ((lo and (r.get("sessionDate") or "") and r["sessionDate"] < lo)
+ or (hi and (r.get("sessionDate") or "") and r["sessionDate"] > hi))
+ ]
+ hits: dict[str, dict[str, Any]] = {}
+ note = None
+ if search:
+ terms = self._search_terms(in_window)
+ hits = search_index.query(terms, search)
+ if not hits and " " in search:
+ fallback = search_index.argument_fallback(terms, search)
+ if fallback:
+ prefix, hits = fallback
+ note = {"code": "arguments", "command": prefix}
out = []
- for r in rows:
- day = r.get("sessionDate") or ""
- if lo and day and day < lo:
- continue
- if hi and day and day > hi:
- continue
+ for r in in_window:
if search:
hay = " ".join(
[str(r.get("sessionTitle") or ""), str(r.get("sessionId") or ""), str(r.get("agentTool") or ""),
" ".join(map(str, r.get("repos") or [])), " ".join(map(str, r.get("models") or []))]
).lower()
- if search not in hay:
+ if search not in hay and r.get("sessionId") not in hits:
continue
out.append(r)
+ if hits:
+ # Ranked by matches, then recency; title-only matches after.
+ out.sort(key=lambda r: (-(hits.get(r.get("sessionId"), {}).get("count") or 0),
+ "" if r.get("sessionId") in hits else "1"))
start = _cursor_decode((q.get("cursor") or [None])[0])
if start is None:
return self._error(400, "invalid_input", "That page cursor is not valid.")
@@ -425,7 +593,9 @@ class _Handler(BaseHTTPRequestHandler):
more = start + size < len(out)
self._json({
"success": True,
- "sessions": [_public_row(r) for r in page],
+ "sessions": [{**_public_row(r), **({"search": hits[r["sessionId"]]} if r.get("sessionId") in hits else {})}
+ for r in page],
+ "searchNote": note,
"nextCursor": _cursor_encode(start + size) if more else None,
"hasMore": more,
})
@@ -555,7 +725,11 @@ def serve(
``scanning``: set while a background scan runs; ``/api/status`` reports it.
"""
- handler = type("Handler", (_Handler,), {"store": store or Store(), "static": viewer_root(), "scanning": scanning})
+ handler = type("Handler", (_Handler,), {
+ "store": store or Store(), "static": viewer_root(), "scanning": scanning,
+ # Per server, so two servers in one process never share computed facts or postings.
+ "facts_cache": {}, "search_mem": {}, "search_file": (None, {}),
+ })
try:
return _Server((host, port), handler)
except OSError:
diff --git a/python/tests/test_builder.py b/python/tests/test_builder.py
index eec2b14..39a1560 100644
--- a/python/tests/test_builder.py
+++ b/python/tests/test_builder.py
@@ -11,7 +11,7 @@ from types import SimpleNamespace
import pytest
from agentplay import builder as sm
-from agentplay import facts
+from agentplay import facts, search
SECRET_PROMPT = "please fix the SECRET-PROMPT-TEXT in billing"
SECRET_ARG = "--token=hunter2-SECRET-ARG"
@@ -230,8 +230,8 @@ def test_acompact_snapshot_is_not_a_subagent_lane(transcript):
def test_builder_never_leaks_free_text(transcript):
doc = sm.build_claude_code_map(transcript)
- # Session facts (the Insights summary on the index row) are held to the same contract.
- raw = json.dumps(doc) + json.dumps(facts.compute(doc))
+ # Session facts and search postings are held to the same contract as the map.
+ raw = json.dumps(doc) + json.dumps(facts.compute(doc)) + json.dumps(search.postings(doc))
for secret in (
"SECRET-PROMPT-TEXT",
"hunter2",
diff --git a/python/tests/test_facts.py b/python/tests/test_facts.py
index f36d0cb..599749a 100644
--- a/python/tests/test_facts.py
+++ b/python/tests/test_facts.py
@@ -55,7 +55,8 @@ def test_commands_files_prompt_and_verify():
_ev(7, "user", chars=30),
])
f = facts.compute(doc)
- assert f["cmd"]["pytest"] == {"calls": 3, "fails": 1, "retries": 1, "byClass": {"exit_code": 1}}
+ assert f["cmd"]["pytest"] == {"calls": 3, "fails": 1, "retries": 1, "byClass": {"exit_code": 1},
+ "verify": True, "outBytes": 0}
assert f["files"] == {"acme/api:src/a.ts": {"hits": 3, "reads": 2, "edits": 1}} # untouched files dropped
assert f["firstPromptChars"] == 420 and f["userTurns"] == 2
assert f["edited"] is True and f["verifyAfterLastEdit"] is True
diff --git a/python/tests/test_search_health_fixes.py b/python/tests/test_search_health_fixes.py
new file mode 100644
index 0000000..e580348
--- /dev/null
+++ b/python/tests/test_search_health_fixes.py
@@ -0,0 +1,292 @@
+"""Search (`search.py`), Run health (`health.py`), writing fixes (`fixes.py`) and Autotune."""
+
+from __future__ import annotations
+
+import http.client
+import json
+import subprocess
+import threading
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from agentplay import autotune, facts, fixes, health, search
+from agentplay.server import serve
+from agentplay.store import Store
+
+DEMO = Path(__file__).resolve().parents[2] / "viewer" / "public" / "demo"
+
+
+def _demo(name: str = "claude-code-rate-limit.json") -> dict[str, Any]:
+ return json.loads((DEMO / name).read_text(encoding="utf-8"))
+
+
+# ------------------------------------------------------------------ search
+
+
+def test_postings_cover_files_commands_mcp_and_errors():
+ p = search.postings(_demo())
+ assert any(t.startswith("file:acme/api:src/middleware/") for t in p)
+ assert "cmd:npm test" in p and "cmd:git push" in p
+ assert "mcp:docs" in p and "mcp:docs/search_docs" in p
+ assert "err:exit_code" in p
+ assert "model:claude-opus-4-5" in p and "repo:acme/api" in p
+ assert [28, "fail"] in p["cmd:npm test"]
+
+
+def test_query_ranks_chips_and_facets():
+ terms = {"a": search.postings(_demo()), "b": search.postings(_demo("codex-flaky-test.json"))}
+ hits = search.query(terms, "cmd:npm test")
+ assert set(hits) == {"a"}
+ chips = hits["a"]["chips"]
+ assert chips[0]["touch"] == "fail" and chips[0]["label"].startswith("failed npm test")
+ assert chips[0]["seq"] == 28
+ assert search.query(terms, "file:index.ts") # basename matches a path
+ assert search.query(terms, "nothing-like-this") == {}
+
+
+def test_arguments_are_never_searchable_but_fall_back_to_the_command():
+ terms = {"a": search.postings(_demo())}
+ assert search.query(terms, "npm test --watch") == {}
+ prefix, hits = search.argument_fallback(terms, "npm test --watch")
+ assert prefix == "npm test" and "a" in hits
+
+
+def test_search_index_holds_no_free_text():
+ doc = _demo()
+ raw = json.dumps(search.postings(doc))
+ assert "Add rate limiting" not in raw # the demo's title is prompt text
+
+
+def test_refresh_reads_only_changed_maps(tmp_path):
+ st = Store(tmp_path)
+ doc = _demo()
+ st.put(doc, {"sessionId": doc["session"]["id"], "contentHash": "h1", "calls": 1})
+ st.save_index()
+ assert search.refresh(st) == 1
+ assert search.refresh(st) == 0
+ st.index[doc["session"]["id"]]["contentHash"] = "h2"
+ assert search.refresh(st) == 1
+
+
+# ------------------------------------------------------------------ health
+
+
+def _row(sid: str, repo: str = "acme/api", **f: Any) -> dict[str, Any]:
+ base = {"edited": True, "prsCreated": 0, "verifyAfterLastEdit": False, "calls": 20, "errors": 0, "retries": 0,
+ "hasCost": True, "tokens": {"in": 100, "cw": 100, "cr": 800}, "compactions": 0, "files": {},
+ "rereadsAfterCompaction": 0, "errorsBySource": {}, "cmd": {}, "costUsd": 1.0}
+ return {"sessionId": sid, "repos": [repo], "facts": {**base, **f}}
+
+
+def test_score_needs_ten_sessions_and_sums_components():
+ rows = [_row(f"s{i}", prsCreated=1 if i < 5 else 0, verifyAfterLastEdit=i < 8) for i in range(10)]
+ t = health.totals(rows)
+ c = health.components(t)
+ assert c["shipping"] == 0.5 and c["verification"] == 0.8
+ assert c["efficiency"] == pytest.approx(0.5 * 1 + 0.5 * 0.8)
+ assert health.score(t) == pytest.approx(20 * (0.5 + 0.8 + 0.9 + 1 + 1))
+ assert health.score(health.totals(rows[:9])) is None
+
+
+def test_verify_fix_names_the_commands_that_pass_and_its_points():
+ cmd = {"pytest": {"calls": 4, "fails": 1, "retries": 0, "byClass": {}, "verify": True, "outBytes": 0}}
+ rows = [_row(f"s{i}", cmd=cmd, verifyAfterLastEdit=i < 2) for i in range(10)]
+ (fx,) = [f for f in health.fixes(rows) if f["rule"] == "verify_before_stop"]
+ assert fx["actions"][0] == {"kind": "stop_hook", "label": "Add Stop hook", "file": ".claude/settings.json",
+ "command": "pytest"}
+ assert "`pytest`" in fx["actions"][1]["lines"][0]
+ assert fx["points"] == pytest.approx(10.0) # 2/10 verified -> 7/10 target: +0.5 x 20
+
+
+def test_no_fix_without_a_named_cause():
+ rows = [_row(f"s{i}") for i in range(10)] # unverified, but no verify command ever passed
+ assert [f["rule"] for f in health.fixes(rows)] == []
+
+
+def test_failing_command_with_a_passing_sibling():
+ cmd = {"pnpm test": {"calls": 10, "fails": 8, "retries": 4, "byClass": {"exit_code": 8}, "outBytes": 0},
+ "pnpm vitest": {"calls": 6, "fails": 0, "retries": 0, "byClass": {}, "verify": True, "outBytes": 0}}
+ rows = [_row("s1", cmd=cmd, errors=8, retries=4, verifyAfterLastEdit=True)]
+ (fx,) = [f for f in health.fixes(rows) if f["rule"] == "use_working_command"]
+ assert fx["title"] == "Use `pnpm vitest` instead of `pnpm test`"
+ assert fx["points"] > 0
+
+
+def test_permission_fix_needs_three_sessions():
+ deny = {"git push": {"calls": 2, "fails": 2, "retries": 0, "byClass": {"permission_denied": 2}, "outBytes": 0}}
+ rows = [_row(f"s{i}", cmd=deny, verifyAfterLastEdit=True,
+ errorsBySource={"tool": {"permission_denied": 2}}) for i in range(3)]
+ (fx,) = [f for f in health.fixes(rows) if f["rule"] == "allow_command"]
+ assert fx["actions"][0]["entry"] == "Bash(git push:*)"
+ assert not [f for f in health.fixes(rows[:2]) if f["rule"] == "allow_command"]
+
+
+# ------------------------------------------------------------------ writing fixes
+
+
+def repo(tmp_path):
+ root = tmp_path / "checkout"
+ root.mkdir()
+ subprocess.run(["git", "init", "-q", str(root)], check=True)
+ base = tmp_path / "home"
+ base.mkdir()
+ fixes.record_roots(base, {"acme/api": str(root)})
+ return base, root
+
+
+FIX = {"id": "abc123", "repo": "acme/api", "title": "t", "rule": "r", "metric": None}
+MD = {"kind": "claude_md", "file": "CLAUDE.md", "lines": ["Run `pytest -q`."]}
+
+
+def test_writes_need_a_grant(repo):
+ base, _ = repo
+ with pytest.raises(fixes.FixError) as exc:
+ fixes.apply(base, FIX, MD)
+ assert exc.value.code == "not_granted"
+
+
+def test_claude_md_block_keeps_the_persons_text_and_undoes(repo):
+ base, root = repo
+ fixes.grant(base, "acme/api")
+ (root / "CLAUDE.md").write_text("# My notes\n\nKeep this.\n")
+ entry = fixes.apply(base, FIX, MD)
+ text = (root / "CLAUDE.md").read_text()
+ assert text.startswith("# My notes\n\nKeep this.\n")
+ assert fixes.START in text and "Run `pytest -q`." in text
+ fixes.apply(base, {**FIX, "id": "zzz"}, {**MD, "lines": ["Second."]})
+ assert (root / "CLAUDE.md").read_text().count(fixes.START) == 1 # one block, two lines
+ fixes.undo(base, entry["id"])
+ text = (root / "CLAUDE.md").read_text()
+ assert "Run `pytest -q`." not in text and "Second." in text and "Keep this." in text
+
+
+def test_settings_are_merged_and_bad_json_is_left_alone(repo):
+ base, root = repo
+ fixes.grant(base, "acme/api")
+ (root / ".claude").mkdir()
+ (root / ".claude/settings.local.json").write_text('{"permissions": {"allow": ["Bash(ls:*)"]}, "model": "x"}')
+ allow = {"kind": "settings_allow", "file": ".claude/settings.local.json", "entry": "Bash(git push:*)"}
+ entry = fixes.apply(base, FIX, allow)
+ data = json.loads((root / ".claude/settings.local.json").read_text())
+ assert data == {"permissions": {"allow": ["Bash(ls:*)", "Bash(git push:*)"]}, "model": "x"}
+ fixes.undo(base, entry["id"])
+ assert json.loads((root / ".claude/settings.local.json").read_text())["permissions"]["allow"] == ["Bash(ls:*)"]
+ (root / ".claude/settings.json").write_text("{not json")
+ with pytest.raises(fixes.FixError) as exc:
+ fixes.apply(base, FIX, {"kind": "stop_hook", "file": ".claude/settings.json", "command": "pytest"})
+ assert exc.value.code == "bad_json"
+
+
+def test_refuses_other_files_symlinks_and_stale_previews(repo, tmp_path):
+ base, root = repo
+ fixes.grant(base, "acme/api")
+ with pytest.raises(fixes.FixError):
+ fixes.apply(base, FIX, MD, rel="../escape.md")
+ outside = tmp_path / "outside.md"
+ outside.write_text("x")
+ (root / "CLAUDE.local.md").symlink_to(outside)
+ with pytest.raises(fixes.FixError) as exc:
+ fixes.apply(base, FIX, MD, rel="CLAUDE.local.md")
+ assert exc.value.code == "outside_repo"
+ with pytest.raises(fixes.FixError) as exc:
+ fixes.apply(base, FIX, MD, expect_hash="0" * 16)
+ assert exc.value.code == "changed"
+
+
+# ------------------------------------------------------------------ autotune
+
+
+def _seed_store(base: Path, n: int = 12) -> Store:
+ st = Store(base)
+ cmd_base = _demo()
+ for i in range(n):
+ doc = json.loads(json.dumps(cmd_base))
+ doc["session"]["id"] = f"s{i}"
+ doc["session"]["startedAt"] = "2099-01-01T00:00:00.000Z"
+ row = {"sessionId": f"s{i}", "sessionDate": "2099-01-01", "startedAt": "2099-01-01T00:00:00.000Z",
+ "repos": ["acme/api"], "calls": 5, "contentHash": f"h{i}"}
+ f = facts.compute(doc)
+ f["cmd"]["pytest"] = {"calls": 4, "fails": 0, "retries": 0, "byClass": {}, "verify": True, "outBytes": 0}
+ f["verifyAfterLastEdit"] = False
+ st.put(doc, {**row, "facts": f, "factsVersion": facts.FACTS_VERSION})
+ st.save_index()
+ return st
+
+
+def test_autotune_writes_local_instructions_and_queues_hooks(repo, monkeypatch):
+ base, root = repo
+ st = _seed_store(base)
+ monkeypatch.setattr(autotune, "WINDOW_DAYS", 100000)
+ assert autotune.run(st)["applied"] == [] # nothing is enabled yet
+ fixes.grant(base, "acme/api")
+ autotune.set_repo(base, "acme/api", enabled=True)
+ res = autotune.run(st, force=True)
+ assert res["applied"] == ["Run the passing checks before the agent stops"]
+ assert "pytest" in (root / "CLAUDE.local.md").read_text()
+ assert not (root / "CLAUDE.md").exists()
+ assert autotune.run(st)["skipped"] == "already ran today"
+
+
+# ------------------------------------------------------------------ routes
+
+
+def _req(httpd, method: str, path: str, body: Any = None, origin: bool = True):
+ conn = http.client.HTTPConnection("127.0.0.1", httpd.server_address[1], timeout=10)
+ headers = {"Content-Type": "application/json"}
+ if origin:
+ headers["Origin"] = f"http://127.0.0.1:{httpd.server_address[1]}"
+ conn.request(method, path, body=json.dumps(body) if body is not None else None, headers=headers)
+ resp = conn.getresponse()
+ out = json.loads(resp.read() or b"{}")
+ conn.close()
+ return resp.status, out
+
+
+def test_health_route_and_writes_through_the_api(repo):
+ base, root = repo
+ st = _seed_store(base)
+ httpd = serve(0, store=st)
+ threading.Thread(target=httpd.serve_forever, kwargs={"poll_interval": 0.05}, daemon=True).start()
+ try:
+ status, body = _req(httpd, "GET", "/api/health?from=2098-12-01&to=2099-01-01")
+ assert status == 200 and body["sessions"] == 12 and body["score"] is not None
+ fx = next(f for f in body["fixes"] if f["rule"] == "verify_before_stop")
+ status, _ = _req(httpd, "POST", "/api/fix", {"action": "apply", "fix": fx["id"], "i": 1,
+ "from": "2098-12-01", "to": "2099-01-01"})
+ assert status == 409 # not granted yet
+ status, _ = _req(httpd, "POST", "/api/repos", {"action": "grant", "repo": "acme/api"}, origin=False)
+ assert status == 403 # writes need the viewer's own Origin
+ status, _ = _req(httpd, "POST", "/api/repos", {"action": "grant", "repo": "acme/api"})
+ assert status == 200
+ status, prev = _req(httpd, "GET", f"/api/fix-preview?fix={fx['id']}&i=1&from=2098-12-01&to=2099-01-01")
+ assert status == 200 and "pytest" in prev["after"]
+ status, done = _req(httpd, "POST", "/api/fix", {"action": "apply", "fix": fx["id"], "i": 1, "hash": prev["hash"],
+ "from": "2098-12-01", "to": "2099-01-01"})
+ assert status == 200 and (root / "CLAUDE.md").exists()
+ status, _ = _req(httpd, "POST", "/api/fix", {"action": "undo", "entry": done["entry"]["id"]})
+ assert status == 200 and "pytest" not in (root / "CLAUDE.md").read_text()
+ status, at = _req(httpd, "GET", "/api/autotune")
+ assert status == 200 and at["repos"][0]["granted"] is True
+ finally:
+ httpd.shutdown()
+ httpd.server_close()
+
+
+def test_sessions_search_returns_chips(tmp_path):
+ st = Store(tmp_path)
+ doc = _demo()
+ st.put(doc, {"sessionId": doc["session"]["id"], "sessionDate": "2026-09-24", "calls": 5, "contentHash": "x"})
+ st.save_index()
+ httpd = serve(0, store=st)
+ threading.Thread(target=httpd.serve_forever, kwargs={"poll_interval": 0.05}, daemon=True).start()
+ try:
+ _, page = _req(httpd, "GET", "/api/sessions?search=cmd%3Anpm%20test")
+ assert page["sessions"][0]["search"]["chips"][0]["seq"] == 28
+ _, page = _req(httpd, "GET", "/api/sessions?search=npm%20test%20--watch")
+ assert page["searchNote"] == {"code": "arguments", "command": "npm test"}
+ finally:
+ httpd.shutdown()
+ httpd.server_close()
diff --git a/viewer/public/demo/index.json b/viewer/public/demo/index.json
index 8cd61b8..c6c0200 100644
--- a/viewer/public/demo/index.json
+++ b/viewer/public/demo/index.json
@@ -80,25 +80,57 @@
"retries": 1,
"byClass": {
"exit_code": 1
- }
+ },
+ "verify": true,
+ "outBytes": 0
},
"tsc": {
"calls": 1,
"fails": 0,
"retries": 0,
- "byClass": {}
+ "byClass": {},
+ "verify": false,
+ "outBytes": 0
},
- "git": {
- "calls": 4,
+ "git status": {
+ "calls": 1,
+ "fails": 0,
+ "retries": 0,
+ "byClass": {},
+ "verify": false,
+ "outBytes": 0
+ },
+ "git diff": {
+ "calls": 1,
+ "fails": 0,
+ "retries": 0,
+ "byClass": {},
+ "verify": false,
+ "outBytes": 0
+ },
+ "git commit": {
+ "calls": 1,
"fails": 0,
"retries": 0,
- "byClass": {}
+ "byClass": {},
+ "verify": false,
+ "outBytes": 0
},
- "gh": {
+ "git push": {
"calls": 1,
"fails": 0,
"retries": 0,
- "byClass": {}
+ "byClass": {},
+ "verify": false,
+ "outBytes": 0
+ },
+ "gh pr_create": {
+ "calls": 1,
+ "fails": 0,
+ "retries": 0,
+ "byClass": {},
+ "verify": false,
+ "outBytes": 0
}
},
"errorsByClass": {
@@ -181,9 +213,28 @@
},
"stallMs": 0,
"firstPromptChars": 1180,
- "userTurns": 3
+ "userTurns": 3,
+ "mcp": {
+ "docs": {
+ "calls": 1,
+ "fails": 0
+ }
+ },
+ "hookFails": {},
+ "subagents": {
+ "Explore": {
+ "launches": 1,
+ "noResult": 0
+ }
+ },
+ "explore": 4,
+ "act": 15,
+ "editedFiles": 6,
+ "blindEdits": 2,
+ "reworkEdits": 0,
+ "stepsToFirstEdit": 5
},
- "factsVersion": 1
+ "factsVersion": 2
},
{
"sessionId": "local:codex:0199a3b2-demo-4f0c-8e55-000000000002",
@@ -252,7 +303,9 @@
"retries": 1,
"byClass": {
"exit_code": 1
- }
+ },
+ "verify": true,
+ "outBytes": 0
},
"pnpm": {
"calls": 1,
@@ -260,19 +313,25 @@
"retries": 0,
"byClass": {
"exit_code": 1
- }
+ },
+ "verify": false,
+ "outBytes": 0
},
"pnpm lint": {
"calls": 1,
"fails": 0,
"retries": 0,
- "byClass": {}
+ "byClass": {},
+ "verify": true,
+ "outBytes": 0
},
- "git": {
+ "git commit": {
"calls": 1,
"fails": 0,
"retries": 0,
- "byClass": {}
+ "byClass": {},
+ "verify": false,
+ "outBytes": 0
}
},
"errorsByClass": {
@@ -319,9 +378,18 @@
},
"stallMs": 0,
"firstPromptChars": 640,
- "userTurns": 2
+ "userTurns": 2,
+ "mcp": {},
+ "hookFails": {},
+ "subagents": {},
+ "explore": 4,
+ "act": 7,
+ "editedFiles": 2,
+ "blindEdits": 0,
+ "reworkEdits": 0,
+ "stepsToFirstEdit": 7
},
- "factsVersion": 1
+ "factsVersion": 2
},
{
"sessionId": "local:cursor:c1d2e3f4-demo-4a5b-9c8d-000000000003",
@@ -407,9 +475,18 @@
},
"stallMs": 0,
"firstPromptChars": 180,
- "userTurns": 1
+ "userTurns": 1,
+ "mcp": {},
+ "hookFails": {},
+ "subagents": {},
+ "explore": 2,
+ "act": 2,
+ "editedFiles": 2,
+ "blindEdits": 1,
+ "reworkEdits": 0,
+ "stepsToFirstEdit": 2
},
- "factsVersion": 1
+ "factsVersion": 2
}
]
}