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

package/tools/fleet_ledger.py

@@ -0,0 +1,272 @@
+#!/usr/bin/env python3
+r"""
+Fleet Outcome Ledger — append-only audit trail for dispatched agents.
+
+Subcommands:
+  append <timestamp> <agent_type> <model> <duration_sec> <tokens_in> <tokens_out> [verdict]
+    Manually append one ledger line (verdict = OK|FAILED|EMPTY|HUNG, default OK)
+  harvest
+    Scan session tasks directories for agent outcomes and append missing entries.
+    (Tracks state in ledger directory for resume capability)
+  rotate
+    Archive ledger lines exceeding ~200 lines to dated archive, keep recent tail in live ledger
+
+Ledger format (markdown table):
+  | ISO ts | agent_type | model | duration_sec | tokens_in | tokens_out | verdict |
+
+Environment:
+  AESOP_STATE_ROOT: Path to state directory (default: ./state relative to cwd)
+  AESOP_TEMP_ROOT: Path to temp directory for tasks scanning (optional)
+"""
+
+import sys
+import json
+import os
+from pathlib import Path
+from datetime import datetime, timezone
+import re
+from collections import defaultdict
+
+
+def get_state_dir():
+    """Resolve state directory from env var or current working directory."""
+    if os.environ.get("AESOP_STATE_ROOT"):
+        return Path(os.environ["AESOP_STATE_ROOT"])
+    return Path.cwd() / "state"
+
+
+def get_ledger_paths():
+    """Get ledger file and sidecar state file paths."""
+    state_dir = get_state_dir()
+    ledger_dir = state_dir / "ledger"
+    ledger_file = ledger_dir / "OUTCOMES-LEDGER.md"
+    harvest_state_file = ledger_dir / ".fleet-ledger-harvest.json"
+    return ledger_file, harvest_state_file, ledger_dir
+
+
+def ensure_ledger_header():
+    """Ensure ledger file exists with markdown table header."""
+    ledger_file, _, ledger_dir = get_ledger_paths()
+    if not ledger_file.exists():
+        ledger_dir.mkdir(parents=True, exist_ok=True)
+        header = '| ISO ts | agent_type | model | duration_sec | tokens_in | tokens_out | verdict |\n'
+        header += '|--------|------------|-------|--------------|-----------|------------|--------|\n'
+        ledger_file.write_text(header, encoding='utf-8')
+
+
+def append_ledger_line(iso_ts, agent_type, model, duration_sec, tokens_in, tokens_out, verdict='OK'):
+    """Append one line to the ledger."""
+    ensure_ledger_header()
+    ledger_file, _, _ = get_ledger_paths()
+
+    # Sanitize fields: no pipes, truncate to reasonable length
+    agent_type = str(agent_type or '-').replace('|', '').strip()[:30]
+    model = str(model or '-').replace('|', '').strip()[:30]
+    verdict = str(verdict or 'OK').replace('|', '').strip()[:10]
+
+    try:
+        dur = int(duration_sec) if duration_sec else 0
+    except (ValueError, TypeError):
+        dur = 0
+
+    try:
+        ti = int(tokens_in) if tokens_in else 0
+    except (ValueError, TypeError):
+        ti = 0
+
+    try:
+        to = int(tokens_out) if tokens_out else 0
+    except (ValueError, TypeError):
+        to = 0
+
+    line = f'| {iso_ts} | {agent_type} | {model} | {dur} | {ti} | {to} | {verdict} |\n'
+    with open(ledger_file, 'a', encoding='utf-8') as f:
+        f.write(line)
+
+
+def load_harvest_state():
+    """Load last-harvest state (set of already-seen agent IDs)."""
+    _, harvest_state_file, _ = get_ledger_paths()
+    if harvest_state_file.exists():
+        try:
+            data = json.loads(harvest_state_file.read_text(encoding='utf-8'))
+            return set(data.get('seen_agents', [])), data.get('last_harvest_ts', None)
+        except (json.JSONDecodeError, IOError):
+            pass
+    return set(), None
+
+
+def save_harvest_state(seen_agents, last_harvest_ts=None):
+    """Save last-harvest state."""
+    _, harvest_state_file, ledger_dir = get_ledger_paths()
+    ledger_dir.mkdir(parents=True, exist_ok=True)
+    state = {
+        'seen_agents': sorted(list(seen_agents)),
+        'last_harvest_ts': last_harvest_ts or datetime.now(timezone.utc).isoformat()
+    }
+    harvest_state_file.write_text(json.dumps(state, indent=2), encoding='utf-8')
+
+
+def harvest():
+    """Scan task output files and append missing agent outcomes."""
+    ensure_ledger_header()
+    seen_agents, _ = load_harvest_state()
+    new_seen = set(seen_agents)
+    harvested_count = 0
+
+    # Determine temp root for tasks scanning
+    if os.environ.get("AESOP_TEMP_ROOT"):
+        temp_root = Path(os.environ["AESOP_TEMP_ROOT"])
+    else:
+        # Default to system temp + /claude
+        import tempfile
+        temp_root = Path(tempfile.gettempdir()) / "claude"
+
+    # Find all .output files in tasks directories
+    for output_file in temp_root.rglob('tasks/*.output'):
+        if not output_file.is_file():
+            continue
+
+        try:
+            content = output_file.read_text(encoding='utf-8', errors='ignore')
+        except (IOError, OSError):
+            continue
+
+        # Parse JSONL: each line is a JSON object
+        for line_idx, line in enumerate(content.split('\n')):
+            if not line.strip():
+                continue
+
+            try:
+                obj = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+
+            # Look for agent spawn events (type='assistant' with Agent/Task tool_use)
+            # or completion events (type='assistant' with usage data)
+            agent_id = obj.get('agentId') or obj.get('uuid')
+            if not agent_id:
+                continue
+
+            # Skip if already seen
+            if agent_id in seen_agents:
+                continue
+
+            # Try to extract completion info
+            msg = obj.get('message', {})
+            ts = obj.get('timestamp', '')
+            msg_type = msg.get('type', '')
+
+            # Look for assistant message with usage (indicates completion)
+            if msg_type == 'message' and msg.get('role') == 'assistant':
+                usage = msg.get('usage', {})
+                if usage:
+                    # Found a completion event
+                    agent_type = 'Agent'  # placeholder; ideally track subagent_type from spawn
+                    model = msg.get('model', '-')
+
+                    # Try to extract duration from timestamps or usage
+                    input_tokens = usage.get('input_tokens', 0)
+                    output_tokens = usage.get('output_tokens', 0)
+
+                    # Verdict: assume OK if no stop_reason error
+                    stop_reason = msg.get('stop_reason')
+                    verdict = 'OK'
+                    if stop_reason in ('error', 'end_turn'):
+                        verdict = 'OK'  # normal completion
+                    elif not stop_reason:
+                        verdict = 'OK'
+
+                    duration_sec = 0  # TODO: parse from timestamps if available
+
+                    # Append to ledger
+                    if ts:
+                        append_ledger_line(ts[:19], agent_type, model, duration_sec,
+                                         input_tokens, output_tokens, verdict)
+                        new_seen.add(agent_id)
+                        harvested_count += 1
+
+        # Save state after processing each file to avoid re-processing
+        save_harvest_state(new_seen)
+
+    ledger_file, _, _ = get_ledger_paths()
+    print(f'Harvested {harvested_count} new agent outcomes to {ledger_file}')
+    return harvested_count
+
+
+def rotate():
+    """Archive old ledger lines if ledger exceeds ~200 lines."""
+    ensure_ledger_header()
+    ledger_file, _, ledger_dir = get_ledger_paths()
+
+    try:
+        lines = ledger_file.read_text(encoding='utf-8').split('\n')
+    except (IOError, OSError):
+        print('Error reading ledger')
+        return
+
+    # Count non-header lines
+    data_lines = [l for l in lines if l.strip() and not l.startswith('|---|')]
+    header_lines = [l for l in lines if l.startswith('|') and '---|' in l]
+
+    if len(data_lines) <= 202:  # Leave some headroom
+        print(f'Ledger has {len(data_lines)} lines; no rotation needed (threshold: 200)')
+        return
+
+    # Create archive with date stamp
+    archive_dir = ledger_dir / "archives"
+    archive_dir.mkdir(parents=True, exist_ok=True)
+    archive_name = datetime.now(timezone.utc).strftime('FLEET-LEDGER-%Y%m%d-%H%M%S.md')
+    archive_file = archive_dir / archive_name
+
+    # Write header + oldest 50% of data lines to archive
+    archive_count = len(data_lines) // 2
+    archive_lines = header_lines + data_lines[:archive_count]
+    archive_file.write_text('\n'.join(archive_lines) + '\n', encoding='utf-8')
+
+    # Keep header + newest lines in live ledger
+    new_ledger = header_lines + data_lines[archive_count:]
+    ledger_file.write_text('\n'.join(new_ledger) + '\n', encoding='utf-8')
+
+    print(f'Rotated {archive_count} lines to {archive_file}')
+    print(f'Live ledger now has {len(new_ledger) - len(header_lines)} data lines')
+
+
+def main():
+    if len(sys.argv) < 2:
+        print(__doc__)
+        sys.exit(1)
+
+    cmd = sys.argv[1].lower()
+
+    if cmd == 'append':
+        # append <ts> <agent_type> <model> <dur> <tokens_in> <tokens_out> [verdict]
+        if len(sys.argv) < 7:
+            print('Usage: fleet_ledger.py append <ts> <agent_type> <model> <dur_sec> <tokens_in> <tokens_out> [verdict]')
+            sys.exit(1)
+
+        ts = sys.argv[2]
+        agent_type = sys.argv[3]
+        model = sys.argv[4]
+        dur = sys.argv[5]
+        ti = sys.argv[6]
+        to = sys.argv[7] if len(sys.argv) > 7 else '0'
+        verdict = sys.argv[8] if len(sys.argv) > 8 else 'OK'
+
+        append_ledger_line(ts, agent_type, model, dur, ti, to, verdict)
+        print(f'Appended: {ts} {agent_type} {model} {dur}s {ti}->{to} [{verdict}]')
+
+    elif cmd == 'harvest':
+        harvest()
+
+    elif cmd == 'rotate':
+        rotate()
+
+    else:
+        print(f'Unknown command: {cmd}')
+        print(__doc__)
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    main()

package/tools/fleet_prompt_extractor.py

@@ -0,0 +1,134 @@
+"""Extract NEW fleet spawn prompts (Agent/Task) for review cycle with deduplication."""
+import argparse
+import hashlib
+import json
+import os
+import pathlib
+import sys
+from datetime import datetime, timedelta
+
+
+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 new fleet spawn prompts (Agent/Task) for review, with dedup by SHA1."
+    )
+    parser.add_argument(
+        "roots", nargs="+", help="Root directories containing .jsonl transcripts to scan"
+    )
+    parser.add_argument(
+        "-s", "--seen-file", required=True, help="Path to seen-set JSON file for dedup (will be created/updated)"
+    )
+    parser.add_argument(
+        "-m", "--minutes", type=int, default=30, help="Look back this many minutes (default 30)"
+    )
+    parser.add_argument(
+        "-x", "--exclude-session", help="Exclude transcripts from this session ID substring"
+    )
+    parser.add_argument(
+        "--max", type=int, default=20, help="Cap prompts per review cycle (default 20)"
+    )
+
+    args = parser.parse_args()
+
+    # Load seen set
+    seen_set = set()
+    if os.path.exists(args.seen_file):
+        try:
+            with open(args.seen_file, "r", encoding="utf-8") as f:
+                seen_set = set(json.load(f))
+        except Exception:
+            pass
+
+    # Gather .jsonl files
+    files = []
+    for root in args.roots:
+        if os.path.exists(root):
+            files.extend(walk_jsonl(root))
+
+    # Time filter
+    since_ms = (datetime.now() - timedelta(minutes=args.minutes)).timestamp() * 1000
+
+    out = []
+    for fp in files:
+        # Session exclusion
+        if args.exclude_session and args.exclude_session in fp:
+            continue
+
+        try:
+            st = os.stat(fp)
+            if st.st_mtime_ns / 1e6 < since_ms:
+                continue
+        except Exception:
+            continue
+
+        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() or ('"Agent"' not in line and '"Task"' not in line):
+                continue
+            try:
+                obj = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+
+            content = obj.get("message", {}).get("content")
+            if not isinstance(content, list):
+                continue
+
+            for c in content:
+                if c.get("type") != "tool_use" or c.get("name") not in ["Agent", "Task"]:
+                    continue
+
+                prompt = (c.get("input", {}).get("prompt") or c.get("input", {}).get("description") or "").strip()
+                if len(prompt) < 8:
+                    continue
+
+                key = hashlib.sha1(prompt.encode()).hexdigest()[:16]
+                if key in seen_set:
+                    continue
+
+                seen_set.add(key)
+                out.append(
+                    {
+                        "key": key,
+                        "src": base,
+                        "label": (c.get("input", {}).get("description") or "")[:80],
+                        "prompt": prompt[:700],
+                    }
+                )
+
+                if len(out) >= args.max:
+                    break
+
+            if len(out) >= args.max:
+                break
+
+        if len(out) >= args.max:
+            break
+
+    # Write updated seen set
+    pathlib.Path(args.seen_file).parent.mkdir(parents=True, exist_ok=True)
+    with open(args.seen_file, "w", encoding="utf-8") as f:
+        json.dump(sorted(list(seen_set)), f)
+
+    # Output to stdout as JSON
+    sys.stdout.write(json.dumps(out))
+
+
+if __name__ == "__main__":
+    main()

package/tools/healthcheck.py

@@ -0,0 +1,296 @@
+#!/usr/bin/env python3
+"""
+Healthcheck tool — Aggregates fleet health signals.
+
+Checks:
+- Heartbeat ages (watchdog, monitor) from config-driven state paths
+- Tracker open-item counts by lane (state/tracker.json)
+- Security-alert count and severity (state/SECURITY-ALERTS.log, if present)
+- Orchestrator status age and phase (state/orchestrator-status.json)
+
+Output: One line `HEALTH: 🟢|🟡|🔴 <reason>` + compact bullet list of non-green contributors.
+
+Green = all heartbeats fresh + no HIGH alerts
+Yellow = stale heartbeat OR unreviewed MED alert
+Red = HIGH alert OR watchdog dead while agents running
+
+Config read at CALL time. Graceful on missing files (missing = reported, not crash).
+Encoding: UTF-8 always. --json mode outputs machine-readable format.
+"""
+import json
+import os
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from time import time
+
+# Import UI config for state path resolution
+UI_DIR = Path(__file__).parent.parent / "ui"
+if str(UI_DIR) not in sys.path:
+    sys.path.insert(0, str(UI_DIR))
+
+try:
+    import config
+except ImportError:
+    print("ERROR: Unable to import config module from ui/", file=sys.stderr)
+    sys.exit(2)
+
+
+def check_health(json_mode=False):
+    """
+    Aggregate health signals and return health ball + reason.
+
+    Returns:
+        str: Either human-readable "HEALTH: 🟢|🟡|🔴 <reason>\n- bullet list"
+             or JSON string (if json_mode=True)
+    """
+    # Reload config at call time to pick up env vars
+    config.reload()
+
+    issues = []  # List of (severity, message) tuples
+
+    # 1. Check heartbeats
+    watchdog_status = _check_heartbeat("watchdog", config.WATCHDOG_HEARTBEAT, threshold=300)
+    if watchdog_status:
+        issues.append(watchdog_status)
+
+    monitor_status = _check_heartbeat("monitor", config.MONITOR_HEARTBEAT, threshold=3600)
+    if monitor_status:
+        issues.append(monitor_status)
+
+    # 2. Check security alerts
+    alert_status = _check_alerts(config.ALERTS_LOG)
+    if alert_status:
+        issues.append(alert_status)
+
+    # 3. Check orchestrator status
+    orch_status = _check_orchestrator_status(config.ORCH_STATUS_FILE)
+    if orch_status:
+        issues.append(orch_status)
+
+    # 4. Check tracker items (informational, not severity-driving)
+    tracker_info = _check_tracker(config.TRACKER_FILE)
+
+    # Determine ball color based on issue severities
+    ball = "🟢"  # Default green
+    for severity, msg in issues:
+        if severity == "RED":
+            ball = "🔴"
+            break
+        elif severity == "YELLOW" and ball != "🔴":
+            ball = "🟡"
+
+    # Build output
+    if json_mode:
+        return _format_json(ball, issues, tracker_info)
+    else:
+        return _format_human(ball, issues, tracker_info)
+
+
+def _check_heartbeat(name, heartbeat_file, threshold=300):
+    """
+    Check heartbeat freshness.
+
+    Returns:
+        tuple (severity, message) or None if all OK
+    """
+    if not heartbeat_file.exists():
+        return ("YELLOW", f"no {name} heartbeat file")
+
+    try:
+        content = heartbeat_file.read_text(encoding="utf-8").strip()
+        if not content:
+            return ("YELLOW", f"{name} heartbeat empty")
+
+        try:
+            timestamp = int(content)
+        except ValueError:
+            return ("YELLOW", f"{name} heartbeat unparseable")
+
+        age_seconds = int(time()) - timestamp
+        if age_seconds >= threshold * 2:
+            # Watchdog dead while orchestrator might be active
+            if name == "watchdog" and age_seconds >= 600:
+                return ("RED", f"watchdog dead ({age_seconds}s)")
+            return ("YELLOW", f"{name} stale ({age_seconds}s > {threshold}s threshold)")
+        elif age_seconds > threshold:
+            return ("YELLOW", f"{name} stale ({age_seconds}s)")
+
+        return None
+    except Exception as e:
+        return ("YELLOW", f"{name} heartbeat read error: {e}")
+
+
+def _check_alerts(alerts_file):
+    """
+    Check security alerts for HIGH severity.
+
+    Returns:
+        tuple (severity, message) or None if all OK
+    """
+    if not alerts_file.exists():
+        return None
+
+    try:
+        content = alerts_file.read_text(encoding="utf-8").strip()
+        if not content:
+            return None
+
+        lines = content.split("\n")
+        unreviewed = [
+            line.strip() for line in lines
+            if line.strip()
+            and "NOTE:" not in line
+            and "RESOLVED-FP" not in line
+        ]
+
+        if not unreviewed:
+            return None
+
+        # Check for HIGH severity
+        high_count = sum(1 for line in unreviewed if "[HIGH]" in line)
+        if high_count > 0:
+            return ("RED", f"{high_count} HIGH severity alerts")
+
+        # Check for MED severity
+        med_count = sum(1 for line in unreviewed if "[MED]" in line)
+        if med_count > 0:
+            return ("YELLOW", f"{med_count} unreviewed MED alerts")
+
+        if unreviewed:
+            return ("YELLOW", f"{len(unreviewed)} unreviewed alerts")
+
+        return None
+    except Exception as e:
+        return ("YELLOW", f"alert check error: {e}")
+
+
+def _check_orchestrator_status(status_file):
+    """
+    Check orchestrator status age (informational; reports stale status).
+
+    Returns:
+        tuple (severity, message) or None if all OK
+    """
+    if not status_file.exists():
+        return None
+
+    try:
+        content = status_file.read_text(encoding="utf-8").strip()
+        if not content:
+            return None
+
+        data = json.loads(content)
+        if not isinstance(data, dict):
+            return None
+
+        # Check updated_at age
+        updated_at_str = data.get("updated_at", "")
+        if not updated_at_str:
+            return None
+
+        updated_at_str = updated_at_str.rstrip("Z")
+        try:
+            updated_at = datetime.fromisoformat(updated_at_str)
+            age_seconds = int((datetime.now(timezone.utc).replace(tzinfo=None) - updated_at).total_seconds())
+
+            # >1800s (30min) is stale for orchestrator
+            if age_seconds > 1800:
+                return ("YELLOW", f"orchestrator status stale ({age_seconds}s)")
+        except Exception:
+            pass
+
+        return None
+    except Exception as e:
+        return ("YELLOW", f"orchestrator status check error: {e}")
+
+
+def _check_tracker(tracker_file):
+    """
+    Aggregate tracker item counts by lane (informational only).
+
+    Returns:
+        dict or None with lane counts
+    """
+    if not tracker_file.exists():
+        return None
+
+    try:
+        content = tracker_file.read_text(encoding="utf-8").strip()
+        if not content:
+            return None
+
+        data = json.loads(content)
+        if not isinstance(data, dict):
+            return None
+
+        items = data.get("items", [])
+        if not items:
+            return None
+
+        # Count by lane
+        lanes = {}
+        for item in items:
+            lane = item.get("lane", "unknown")
+            if lane not in lanes:
+                lanes[lane] = 0
+            lanes[lane] += 1
+
+        return lanes
+    except Exception:
+        return None
+
+
+def _format_human(ball, issues, tracker_info):
+    """Format human-readable output."""
+    reason = "OK"
+    if issues:
+        reasons = [msg for severity, msg in issues]
+        reason = "; ".join(reasons)
+
+    lines = [f"HEALTH: {ball} {reason}"]
+
+    if tracker_info:
+        lane_str = ", ".join(f"{lane}: {count}" for lane, count in sorted(tracker_info.items()))
+        lines.append(f"  Tracker: {lane_str}")
+
+    return "\n".join(lines)
+
+
+def _format_json(ball, issues, tracker_info):
+    """Format JSON output."""
+    result = {
+        "ball": ball,
+        "health": "OK" if ball == "🟢" else ("DEGRADED" if ball == "🟡" else "CRITICAL"),
+        "issues": [{"severity": severity, "message": msg} for severity, msg in issues],
+        "tracker": tracker_info or {},
+    }
+    return json.dumps(result, indent=2)
+
+
+def main():
+    """CLI entry point."""
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description="Aesop healthcheck — aggregate fleet health signals"
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output as JSON"
+    )
+
+    args = parser.parse_args()
+
+    try:
+        output = check_health(json_mode=args.json)
+        print(output)
+        sys.exit(0)
+    except Exception as e:
+        print(f"ERROR: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()