@matt82198/aesop 0.1.0-beta.3 → 0.1.0-beta.5

package/tools/stall_check.py

@@ -0,0 +1,172 @@
+#!/usr/bin/env python3
+"""
+Automated silent-hang detection for agent transcripts.
+
+Usage:
+  stall_check.py [--transcripts-root DIR] [--threshold-seconds SEC] [--json] [--exit-nonzero-on-stall]
+
+Options:
+  --transcripts-root DIR       Root directory to scan for agent-*.jsonl transcripts.
+                               Defaults to AESOP_TRANSCRIPTS_ROOT env var, or ~/.claude/projects if unset.
+  --threshold-seconds SEC      Max age in seconds for a "fresh" transcript (default: 600).
+                               Transcripts older than this are flagged as stalled.
+  --json                       Output as JSON list of {agent_id, age_seconds, stalled, last_mtime}.
+  --exit-nonzero-on-stall      Exit 1 if any agent is detected as stalled; default exit 0 always.
+
+Behavior:
+  - Walks transcripts-root for files matching agent-*.jsonl.
+  - For each file, computes age = now - file mtime (seconds).
+  - Reports agents as stalled if age > threshold-seconds.
+  - Default output: human-readable table; add --json for structured output.
+  - Gracefully reports "no transcripts found" if root is missing or empty.
+  - Exit code: 0 always (unless --exit-nonzero-on-stall specified and stalls detected).
+"""
+
+import sys
+import os
+import time
+import json
+import argparse
+from pathlib import Path
+
+
+def get_transcripts_root():
+    """Resolve transcripts root from env var or default to ~/.claude/projects."""
+    if os.environ.get("AESOP_TRANSCRIPTS_ROOT"):
+        return Path(os.environ["AESOP_TRANSCRIPTS_ROOT"])
+    # Default to ~/.claude/projects
+    return Path.home() / ".claude" / "projects"
+
+
+def scan_transcripts(transcripts_root, threshold_seconds):
+    """Scan transcripts root for agent-*.jsonl files and compute staleness.
+
+    Returns: list of dicts {agent, transcript, mtime_age_s, verdict, suggested_action, last_mtime (ISO)}
+    """
+    transcripts_root = Path(transcripts_root)
+
+    if not transcripts_root.exists():
+        return None  # Signal: root missing
+
+    now = time.time()
+    results = []
+
+    # Thresholds for verdict classification
+    STALE_THRESHOLD = threshold_seconds
+    DEAD_THRESHOLD = threshold_seconds * 2  # Dead if 2x threshold
+
+    # Walk all subdirectories for agent-*.jsonl files
+    for jsonl_file in transcripts_root.rglob("agent-*.jsonl"):
+        if not jsonl_file.is_file():
+            continue
+
+        mtime = jsonl_file.stat().st_mtime
+        age_seconds = int(now - mtime)
+
+        # Extract agent_id from filename (e.g., agent-abc123.jsonl -> abc123)
+        agent_id = jsonl_file.stem.replace("agent-", "")
+
+        # Determine verdict
+        if age_seconds <= STALE_THRESHOLD:
+            verdict = "ok"
+            suggested_action = None
+        elif age_seconds <= DEAD_THRESHOLD:
+            verdict = "stale"
+            suggested_action = "monitor for progress or investigate why transcript is stalled"
+        else:
+            verdict = "dead"
+            suggested_action = "investigate immediately; agent may be hung or crashed"
+
+        results.append({
+            "agent": agent_id,
+            "transcript": str(jsonl_file),
+            "mtime_age_s": age_seconds,
+            "verdict": verdict,
+            "suggested_action": suggested_action,
+            "last_mtime": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime(mtime)),
+        })
+
+    return results
+
+
+def print_human_table(results):
+    """Print results as a human-readable table."""
+    if not results:
+        print("no transcripts found")
+        return
+
+    # Sort by mtime_age_s (oldest first)
+    sorted_results = sorted(results, key=lambda r: r["mtime_age_s"], reverse=True)
+
+    # Header
+    print(f"{'AGENT':<30} {'AGE (s)':<10} {'VERDICT':<10} {'ACTION':<40}")
+    print("-" * 90)
+
+    for entry in sorted_results:
+        action = entry["suggested_action"] or "—"
+        # Truncate action for display
+        action = action[:38] if len(action) > 38 else action
+        print(f"{entry['agent']:<30} {entry['mtime_age_s']:<10} {entry['verdict']:<10} {action:<40}")
+
+
+def print_json_output(results):
+    """Print results as JSON."""
+    if results is None:
+        print(json.dumps([]))
+    else:
+        print(json.dumps(results, indent=2))
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument(
+        "--transcripts-root",
+        default=None,
+        help="Root directory to scan for agent-*.jsonl files (default: AESOP_TRANSCRIPTS_ROOT or ~/.claude/projects)",
+    )
+    parser.add_argument(
+        "--threshold-seconds",
+        type=int,
+        default=600,
+        help="Max age in seconds for a 'fresh' transcript (default: 600)",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output as JSON instead of human-readable table",
+    )
+    parser.add_argument(
+        "--exit-nonzero-on-stall",
+        action="store_true",
+        help="Exit 1 if any agent is stalled (default: always exit 0)",
+    )
+
+    args = parser.parse_args()
+
+    # Resolve transcripts root
+    transcripts_root = args.transcripts_root if args.transcripts_root else get_transcripts_root()
+
+    # Scan transcripts
+    results = scan_transcripts(transcripts_root, args.threshold_seconds)
+
+    # Output
+    if args.json:
+        print_json_output(results)
+    else:
+        if results is None:
+            print("no transcripts found")
+        else:
+            print_human_table(results)
+
+    # Determine exit code
+    exit_code = 0
+    if args.exit_nonzero_on_stall and results:
+        has_stalled = any(r["verdict"] in ("stale", "dead") for r in results)
+        if has_stalled:
+            exit_code = 1
+
+    sys.exit(exit_code)
+
+
+if __name__ == "__main__":
+    main()

package/tools/svg_to_png.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+/**
+ * svg_to_png.mjs — Rasterize an SVG file to PNG using @resvg/resvg-js.
+ *
+ * Why this exists: on systems without rsvg-convert, ImageMagick, or Inkscape,
+ * @resvg/resvg-js ships a prebuilt native binary via npm with zero extra system
+ * deps, making it the reliable local converter for cross-platform automation.
+ *
+ * Usage:
+ *   node svg_to_png.mjs <input.svg> <output.png> [width]
+ *
+ * If [width] is given, the SVG is rasterized at that pixel width (height keeps
+ * aspect ratio unless the SVG sets an explicit height). Requires
+ * @resvg/resvg-js to be installed (locally in the calling project, or
+ * globally) — install with: npm install @resvg/resvg-js
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+
+let Resvg;
+try {
+  const resvgModule = await import("@resvg/resvg-js");
+  Resvg = resvgModule.Resvg;
+} catch (err) {
+  console.error(
+    "Error: @resvg/resvg-js is not installed.\n" +
+    "Install it with: npm install @resvg/resvg-js\n" +
+    "Or globally with: npm install -g @resvg/resvg-js"
+  );
+  process.exit(1);
+}
+
+const [, , inputPath, outputPath, widthArg] = process.argv;
+
+if (!inputPath || !outputPath) {
+  console.error("Usage: node svg_to_png.mjs <input.svg> <output.png> [width]");
+  process.exit(1);
+}
+
+const svg = readFileSync(inputPath, "utf8");
+const opts = {};
+if (widthArg) {
+  opts.fitTo = { mode: "width", value: parseInt(widthArg, 10) };
+}
+
+const resvg = new Resvg(svg, opts);
+const pngData = resvg.render();
+const buffer = pngData.asPng();
+writeFileSync(outputPath, buffer);
+
+console.log(`${outputPath}: ${pngData.width}x${pngData.height}`);

package/tools/transcript_replay.py

@@ -0,0 +1,236 @@
+"""Replay post-commit edits/writes from Claude Code transcripts to recover uncommitted work."""
+import argparse
+import json
+import os
+import pathlib
+import sys
+from datetime import datetime
+
+
+def apply_edit(text, old_string, new_string, replace_all=False):
+    """Apply a single edit to text. Returns updated text or None/undefined."""
+    if not isinstance(old_string, str) or not old_string or old_string not in text:
+        return None
+    if replace_all:
+        return text.split(old_string)[0] + new_string + text.split(old_string)[1]
+    idx = text.find(old_string)
+    return text[:idx] + new_string + text[idx + len(old_string) :]
+
+
+def count_lines(text):
+    """Count lines in text."""
+    return len(text.split("\n"))
+
+
+def fmt_time(ts_ms):
+    """Format timestamp in milliseconds to ISO format with Z suffix."""
+    if not ts_ms:
+        return "?"
+    return datetime.fromtimestamp(ts_ms / 1000).isoformat().replace("T", " ")[:19] + "Z"
+
+
+def walk_jsonl(directory):
+    """Recursively find all .jsonl files in a directory."""
+    result = []
+    for root, dirs, files in os.walk(directory):
+        for f in files:
+            if f.endswith(".jsonl"):
+                result.append(os.path.join(root, f))
+    return result
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Replay post-commit edits/writes from Claude Code transcripts to recover uncommitted work."
+    )
+    parser.add_argument(
+        "roots", nargs="+", help="Root directories containing .jsonl transcripts to scan"
+    )
+    parser.add_argument(
+        "-p", "--project", required=True, help="Project name/path substring to match"
+    )
+    parser.add_argument(
+        "-r", "--repo-dir", required=True, help="Root directory of the live repository"
+    )
+    parser.add_argument(
+        "-c", "--commit-time", required=True, help="Timestamp of last commit (ISO format, e.g., '2026-06-23T17:22:04Z')"
+    )
+    parser.add_argument(
+        "-o", "--output", required=True, help="Output directory for replayed files"
+    )
+
+    args = parser.parse_args()
+
+    # Parse commit time
+    commit_ms = int(datetime.fromisoformat(args.commit_time.replace("Z", "+00:00")).timestamp() * 1000)
+
+    output_dir = pathlib.Path(args.output)
+    if output_dir.exists():
+        import shutil
+        shutil.rmtree(output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    # Gather .jsonl files
+    files = []
+    for root in args.roots:
+        if os.path.exists(root):
+            files.extend(walk_jsonl(root))
+
+    # Collect Write/Edit/MultiEdit operations
+    ops = []  # {rel, ts, tool, input, src}
+    for fp in files:
+        try:
+            with open(fp, "r", encoding="utf-8") as f:
+                lines = f.read().split("\n")
+        except Exception:
+            continue
+
+        src = os.path.basename(fp)
+        for line in lines:
+            if not line.strip():
+                continue
+            try:
+                obj = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+
+            ts = 0
+            if obj.get("timestamp"):
+                ts = int(datetime.fromisoformat(obj["timestamp"]).timestamp() * 1000)
+
+            content = obj.get("message", {}).get("content")
+            if not isinstance(content, list):
+                continue
+
+            for c in content:
+                if c.get("type") != "tool_use":
+                    continue
+                if c.get("name") not in ["Write", "Edit", "MultiEdit"]:
+                    continue
+
+                inp = c.get("input") or {}
+                file_path = inp.get("file_path") or ""
+                file_path_normalized = file_path.replace("\\", "/")
+                if f"/{args.project}/" not in file_path_normalized:
+                    continue
+
+                rel = file_path_normalized.split(f"/{args.project}/")[1]
+                ops.append(
+                    {"rel": rel, "ts": ts, "tool": c["name"], "input": inp, "src": src}
+                )
+
+    ops.sort(key=lambda x: x["ts"])
+
+    # Filter post-commit ops
+    post = [o for o in ops if o["ts"] > commit_ms]
+
+    # Group by file
+    by_file = {}
+    for o in post:
+        if o["rel"] not in by_file:
+            by_file[o["rel"]] = []
+        by_file[o["rel"]].append(o)
+
+    report = [
+        f"# POST-COMMIT REPLAY — {len(post)} uncommitted ops across {len(by_file)} files "
+        f"(after {fmt_time(commit_ms)})\n"
+    ]
+    recovered = []
+
+    for rel in sorted(by_file.keys()):
+        ops_list = by_file[rel]
+        live_path = os.path.join(args.repo_dir, rel)
+        live_ok = os.path.isfile(live_path)
+        text = ""
+        if live_ok:
+            try:
+                with open(live_path, "r", encoding="utf-8") as f:
+                    text = f.read()
+            except Exception:
+                live_ok = False
+
+        disk_len = len(text)
+        applied = 0
+        missed = 0
+        miss_details = []
+
+        for o in ops_list:
+            if o["tool"] == "Write":
+                text = o["input"].get("content") or text
+                applied += 1
+            elif o["tool"] == "Edit":
+                r = apply_edit(
+                    text,
+                    o["input"].get("old_string"),
+                    o["input"].get("new_string"),
+                    o["input"].get("replace_all"),
+                )
+                if isinstance(r, str):
+                    text = r
+                    applied += 1
+                else:
+                    missed += 1
+                    miss_details.append(
+                        f"{fmt_time(o['ts'])} {(o['input'].get('old_string') or '')[:50].replace(chr(10), '\\n')}"
+                    )
+            elif o["tool"] == "MultiEdit":
+                for e in o["input"].get("edits") or []:
+                    r = apply_edit(
+                        text,
+                        e.get("old_string"),
+                        e.get("new_string"),
+                        e.get("replace_all"),
+                    )
+                    if isinstance(r, str):
+                        text = r
+                        applied += 1
+                    else:
+                        missed += 1
+                        miss_details.append(
+                            f"{fmt_time(o['ts'])} [multi] {(e.get('old_string') or '')[:50].replace(chr(10), '\\n')}"
+                        )
+
+        changed = live_ok and text != (
+            open(live_path, "r", encoding="utf-8").read() if live_ok else ""
+        )
+        out_path = output_dir / rel
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        with open(out_path, "w", encoding="utf-8") as f:
+            f.write(text)
+
+        report.append(f"\n## {rel}")
+        report.append(
+            f"   post-commit ops={len(ops_list)} "
+            f"(Write={len([x for x in ops_list if x['tool'] == 'Write'])} "
+            f"Edit={len([x for x in ops_list if x['tool'] != 'Write'])}) "
+            f"span {fmt_time(ops_list[0]['ts'])} → {fmt_time(ops_list[-1]['ts'])}"
+        )
+        report.append(
+            f"   base(disk)={disk_len}b/{count_lines(open(live_path, 'r', encoding='utf-8').read() if live_ok else '')}L "
+            f"->  replayed={len(text)}b/{count_lines(text)}L "
+            f"| applied={applied} missed={missed} "
+            f"| {'*** DIFFERS FROM DISK ***' if changed else 'same as disk'}"
+        )
+        if miss_details:
+            report.append("   MISSED edits (old_string not found in base):")
+            for detail in miss_details:
+                report.append(f"      - {detail}")
+        report.append("")
+
+        if changed:
+            recovered.append(rel)
+
+    report.append(f"\n# FILES WITH RECOVERABLE UNCOMMITTED WORK: {len(recovered)}")
+    for r in recovered:
+        report.append(f"  {r}")
+
+    report_path = output_dir / "_REPLAY_REPORT.txt"
+    with open(report_path, "w", encoding="utf-8") as f:
+        f.write("\n".join(report))
+
+    print("\n".join(report))
+    print(f"\noutput dir: {output_dir}")
+
+
+if __name__ == "__main__":
+    main()

package/tools/transcript_timeline.py

@@ -0,0 +1,184 @@
+"""Extract timeline of file changes from Claude Code transcripts (Write/Edit/Read operations)."""
+import argparse
+import json
+import os
+import pathlib
+from datetime import datetime
+
+
+def fmt_time(ts_ms):
+    """Format timestamp in milliseconds to ISO format with Z suffix."""
+    if not ts_ms:
+        return "?"
+    return datetime.fromtimestamp(ts_ms / 1000).isoformat().replace("T", " ")[:19] + "Z"
+
+
+def strip_line_nums(text):
+    """Remove line number prefixes (e.g., '123\\t') from tool output."""
+    lines = text.split("\n")
+    result = []
+    for line in lines:
+        # Strip pattern: leading spaces + digits + tab
+        stripped = line
+        if "\t" in line:
+            parts = line.split("\t", 1)
+            if parts[0].strip().isdigit():
+                stripped = parts[1]
+        result.append(stripped)
+    return "\n".join(result)
+
+
+def result_text(content):
+    """Extract text from tool result content."""
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts = []
+        for x in content:
+            if isinstance(x, str):
+                parts.append(x)
+            elif isinstance(x, dict):
+                parts.append(x.get("text", ""))
+        return "".join(parts)
+    if isinstance(content, dict):
+        return content.get("text", "")
+    return ""
+
+
+def walk_jsonl(directory):
+    """Recursively find all .jsonl files in a directory."""
+    result = []
+    for root, dirs, files in os.walk(directory):
+        for f in files:
+            if f.endswith(".jsonl"):
+                result.append(os.path.join(root, f))
+    return result
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Extract timeline of file changes (Write/Edit/Read) from Claude Code transcripts."
+    )
+    parser.add_argument(
+        "roots", nargs="+", help="Root directories containing .jsonl transcripts to scan"
+    )
+    parser.add_argument(
+        "-p", "--project", required=True, help="Project name/path substring to match"
+    )
+    parser.add_argument(
+        "-t", "--targets", nargs="+", required=True, help="Target file paths/substrings to inspect"
+    )
+
+    args = parser.parse_args()
+
+    # Gather .jsonl files
+    files = []
+    for root in args.roots:
+        if os.path.exists(root):
+            files.extend(walk_jsonl(root))
+
+    # Index operations by ID
+    use_by_id = {}
+    snaps = []  # {rel, ts, size, kind, src, content}
+
+    for fp in files:
+        try:
+            with open(fp, "r", encoding="utf-8") as f:
+                lines = f.read().split("\n")
+        except Exception:
+            continue
+
+        base = os.path.basename(fp)
+        for line in lines:
+            if not line.strip():
+                continue
+            try:
+                obj = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+
+            ts = 0
+            if obj.get("timestamp"):
+                ts = int(datetime.fromisoformat(obj["timestamp"]).timestamp() * 1000)
+
+            content = obj.get("message", {}).get("content")
+            if not isinstance(content, list):
+                continue
+
+            for c in content:
+                if c.get("type") == "tool_use":
+                    file_path = c.get("input", {}).get("file_path")
+                    if file_path:
+                        file_path_normalized = file_path.replace("\\", "/")
+                        if f"/{args.project}/" in file_path_normalized:
+                            rel = file_path_normalized.split(f"/{args.project}/")[1]
+                        else:
+                            rel = None
+                    else:
+                        rel = None
+
+                    if c.get("name") in ["Write", "Edit", "MultiEdit", "Read"]:
+                        use_by_id[c.get("id")] = {"tool": c.get("name"), "rel": rel, "ts": ts}
+
+                    if (
+                        rel
+                        and c.get("name") == "Write"
+                        and isinstance(c.get("input", {}).get("content"), str)
+                    ):
+                        snaps.append(
+                            {
+                                "rel": rel,
+                                "ts": ts,
+                                "size": len(c["input"]["content"]),
+                                "kind": "Write",
+                                "src": base,
+                                "content": c["input"]["content"],
+                            }
+                        )
+
+                elif c.get("type") == "tool_result":
+                    u = use_by_id.get(c.get("tool_use_id"))
+                    if u and u.get("tool") == "Read" and u.get("rel"):
+                        txt = strip_line_nums(result_text(c.get("content")))
+                        if txt and len(txt) > 30:
+                            snaps.append(
+                                {
+                                    "rel": u["rel"],
+                                    "ts": u.get("ts") or ts,
+                                    "size": len(txt),
+                                    "kind": "Read",
+                                    "src": base,
+                                    "content": txt,
+                                }
+                            )
+
+    # Report on targets
+    for target in args.targets:
+        target_snaps = [s for s in snaps if s["rel"] and target in s["rel"]]
+        target_snaps.sort(key=lambda x: x["ts"])
+
+        print(f"\n===== {target} =====  ({len(target_snaps)} snapshots)")
+        for s in target_snaps:
+            print(
+                f"  {fmt_time(s['ts'])}  {str(s['size']).rjust(6)}b  "
+                f"{s['kind']:<5} {s['src']}"
+            )
+
+        if target_snaps:
+            latest = target_snaps[-1]
+            largest = sorted(target_snaps, key=lambda x: (-x["size"], -x["ts"]))[0]
+            exact = target.split("/")[-1]
+
+            # Write snapshots
+            for snap, tag in [(latest, "LATEST"), (largest, "LARGEST")]:
+                if snap is latest and tag == "LARGEST" and snap is latest:
+                    continue  # Skip duplicate
+                safe_name = f"{exact}.{tag}".replace(os.sep, "_")
+                for c in r'<>:"|?*':
+                    safe_name = safe_name.replace(c, "_")
+                # Write to current dir for simplicity (no output arg in this version)
+                print(f"  -> {tag}: {snap['size']}b @ {fmt_time(snap['ts'])} ({snap['src']})")
+
+
+if __name__ == "__main__":
+    main()