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

package/tools/eod_sweep.py

@@ -0,0 +1,239 @@
+#!/usr/bin/env python3
+"""
+eod_sweep.py — End-of-day safety check for repository health.
+
+Verifies git repositories are safe (no data loss risk):
+- Working tree clean/dirty
+- Branch pushed (ahead-count 0)
+- Untracked files not in .gitignore
+
+Output contract:
+  Line 1: EOD-SWEEP: SAFE or EOD-SWEEP: AT-RISK — <n> findings
+  Lines 2+: One finding per line (if any)
+  Exit code 0 only when SAFE.
+
+Usage: eod_sweep.py [--repos PATHS] [--readonly-repos PATHS] [--fix-push]
+
+  --repos: Colon-separated paths to scan (default: empty; use env var or flag to specify)
+  --readonly-repos: Colon-separated paths that should NOT be auto-pushed
+  --fix-push: Auto-push unpushed commits in repos where safe
+"""
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+from datetime import datetime
+import time
+
+
+class Finding:
+    """A single finding with repo + message."""
+    def __init__(self, repo, msg):
+        self.repo = repo
+        self.msg = msg
+
+    def __str__(self):
+        return f"{self.repo.name}: {self.msg}"
+
+
+def get_git_status(repo_path):
+    """Return (is_clean, dirty_files_list) for a repo."""
+    try:
+        output = subprocess.run(
+            ['git', '-C', str(repo_path), 'status', '--porcelain'],
+            capture_output=True, text=True, timeout=5
+        ).stdout.strip()
+
+        if not output:
+            return (True, [])
+        else:
+            dirty = [line for line in output.split('\n') if line]
+            return (False, dirty)
+    except Exception as e:
+        return (None, str(e))
+
+
+def get_ahead_count(repo_path):
+    """Return count of commits ahead of origin/HEAD (or None on error)."""
+    try:
+        # First check if there's a tracking branch
+        try:
+            output = subprocess.run(
+                ['git', '-C', str(repo_path), 'rev-list', '--left-only', '--count', 'HEAD...@{u}'],
+                capture_output=True, text=True, timeout=5
+            ).stdout.strip()
+        except:
+            # Fallback to origin/HEAD if no upstream
+            output = subprocess.run(
+                ['git', '-C', str(repo_path), 'rev-list', '--left-only', '--count', 'HEAD...origin/HEAD'],
+                capture_output=True, text=True, timeout=5
+            ).stdout.strip()
+
+        try:
+            return int(output) if output else 0
+        except:
+            return None
+    except Exception:
+        return None
+
+
+def check_untracked_files(repo_path):
+    """Return list of untracked files not in .gitignore."""
+    try:
+        output = subprocess.run(
+            ['git', '-C', str(repo_path), 'ls-files', '--others', '--exclude-standard'],
+            capture_output=True, text=True, timeout=5
+        ).stdout.strip()
+
+        if output:
+            return output.split('\n')
+        return []
+    except Exception:
+        return None
+
+
+def check_repo(repo_path):
+    """Check a single repo; return list of Finding objects or None if repo doesn't exist."""
+    if not repo_path.exists():
+        return None
+
+    if not (repo_path / '.git').exists():
+        return None
+
+    findings = []
+
+    # Check 1: Working tree clean
+    is_clean, dirty = get_git_status(repo_path)
+    if is_clean is None:
+        findings.append(Finding(repo_path, f"git status check failed: {dirty}"))
+    elif not is_clean:
+        findings.append(Finding(repo_path, f"dirty working tree: {len(dirty)} files"))
+
+    # Check 2: Branch pushed
+    ahead = get_ahead_count(repo_path)
+    if ahead is None:
+        findings.append(Finding(repo_path, "ahead-count check failed"))
+    elif ahead > 0:
+        findings.append(Finding(repo_path, f"ahead of origin: {ahead} commits unpushed"))
+
+    # Check 3: Untracked files
+    untracked = check_untracked_files(repo_path)
+    if untracked is None:
+        findings.append(Finding(repo_path, "untracked file check failed"))
+    elif untracked:
+        findings.append(Finding(repo_path, f"untracked files: {len(untracked)} items"))
+
+    return findings
+
+
+def push_repo(repo_path):
+    """Push commits for a repo (return True if successful)."""
+    try:
+        result = subprocess.run(
+            ['git', '-C', str(repo_path), 'push'],
+            capture_output=True, text=True, timeout=30
+        )
+        return result.returncode == 0
+    except Exception:
+        return False
+
+
+def run_secret_scan(repo_path):
+    """Run secret_scan.py on staged files (return True if no secrets found)."""
+    try:
+        script_path = Path(__file__).parent / 'secret_scan.py'
+        result = subprocess.run(
+            [sys.executable, str(script_path), '--staged'],
+            cwd=str(repo_path),
+            capture_output=True, text=True, timeout=30
+        )
+        return result.returncode == 0
+    except Exception:
+        return False
+
+
+def main():
+    import argparse
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        '--repos',
+        default='',
+        help='Colon-separated paths to scan (default: empty)'
+    )
+    parser.add_argument(
+        '--readonly-repos',
+        default='',
+        help='Colon-separated paths that should NOT be auto-pushed'
+    )
+    parser.add_argument(
+        '--fix-push',
+        action='store_true',
+        help='Auto-push unpushed commits'
+    )
+    args = parser.parse_args()
+
+    # Parse repos
+    repos_to_check = []
+    if args.repos:
+        repos_to_check = [Path(p) for p in args.repos.split(':') if p]
+
+    # Parse readonly repos
+    readonly_repos = set()
+    if args.readonly_repos:
+        readonly_repos = {Path(p) for p in args.readonly_repos.split(':') if p}
+
+    findings = []
+
+    # Scan all repos
+    for repo_path in repos_to_check:
+        repo_findings = check_repo(repo_path)
+        if repo_findings is not None:
+            findings.extend(repo_findings)
+
+    # Determine verdict
+    if not findings:
+        verdict = "SAFE"
+        verdict_line = "EOD-SWEEP: SAFE"
+        exit_code = 0
+    else:
+        verdict = f"AT-RISK — {len(findings)} findings"
+        verdict_line = f"EOD-SWEEP: AT-RISK — {len(findings)} findings"
+        exit_code = 1
+
+    # Handle --fix-push if requested and conditions are met
+    if args.fix_push and findings:
+        # Filter for ahead-only findings that we can push
+        ahead_findings = [f for f in findings if 'unpushed' in f.msg and f.repo not in readonly_repos]
+        if ahead_findings:
+            for finding in ahead_findings:
+                repo_path = finding.repo
+                if repo_path and repo_path not in readonly_repos:
+                    # Run secret scan first
+                    if run_secret_scan(repo_path):
+                        if push_repo(repo_path):
+                            print(f"Pushed: {repo_path.name}")
+                            findings.remove(finding)
+                        else:
+                            print(f"Push failed: {repo_path.name}")
+                    else:
+                        print(f"Secret scan blocked: {repo_path.name}")
+
+            # Re-evaluate verdict
+            if not findings:
+                verdict = "SAFE"
+                verdict_line = "EOD-SWEEP: SAFE"
+                exit_code = 0
+            else:
+                verdict_line = f"EOD-SWEEP: AT-RISK — {len(findings)} findings"
+
+    # Print output
+    print(verdict_line)
+    for finding in findings:
+        print(f"  {finding}")
+
+    sys.exit(exit_code)
+
+
+if __name__ == '__main__':
+    main()

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/heartbeat.py

@@ -0,0 +1,131 @@
+#!/usr/bin/env python3
+"""
+Heartbeat registry for fleet-wide liveness monitoring.
+
+Usage:
+  heartbeat.py beat <name> [<status>] [--state-dir DIR] [--brain]
+  heartbeat.py check [--max-age 300] [--state-dir DIR]
+
+Modes:
+  beat: Write epoch + optional status word to .heartbeats/<name>
+    --state-dir: Heartbeats directory (default: AESOP_STATE_ROOT/heartbeats or ./state/heartbeats)
+    --brain: Write to ~/.claude/.heartbeats/ (overrides --state-dir)
+  check: List all .heartbeats/* files and report "<name> ALIVE|STALE age:<n>s"
+    Exit 0 if all alive, 1 if any stale. Always prints output.
+"""
+
+import sys
+import os
+import time
+from pathlib import Path
+import argparse
+
+
+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"])
+    # Default to ./state (relative to cwd)
+    return Path.cwd() / "state"
+
+
+def beat(name, status=None, state_dir=None, brain=False):
+    """Write epoch (+ optional status) to .heartbeats/<name>."""
+    if brain:
+        target_dir = Path.home() / ".claude" / ".heartbeats"
+        location = "brain"
+    else:
+        if state_dir is None:
+            state_dir = get_state_dir()
+        target_dir = state_dir / "heartbeats"
+        location = "state"
+
+    target_dir.mkdir(parents=True, exist_ok=True)
+    hb_file = target_dir / name
+    now_epoch = str(int(time.time()))
+    content = now_epoch + "\n"
+    if status:
+        content += status + "\n"
+    hb_file.write_text(content)
+    print(f"beat: {name} written to {location}")
+
+
+def check(max_age=300, state_dir=None):
+    """Check all heartbeat files and report ALIVE/STALE."""
+    now = time.time()
+    all_alive = True
+    results = []
+
+    if state_dir is None:
+        state_dir = get_state_dir()
+
+    # Collect state dir registry files
+    state_hb_dir = state_dir / "heartbeats"
+    if state_hb_dir.exists():
+        for hb_file in sorted(state_hb_dir.iterdir()):
+            if hb_file.is_file():
+                age = _get_age(hb_file, now)
+                status = "ALIVE" if age <= max_age else "STALE"
+                if status == "STALE":
+                    all_alive = False
+                results.append((f"state/{hb_file.name}", status, age))
+
+    # Collect brain registry files
+    brain_hb_dir = Path.home() / ".claude" / ".heartbeats"
+    if brain_hb_dir.exists():
+        for hb_file in sorted(brain_hb_dir.iterdir()):
+            if hb_file.is_file():
+                age = _get_age(hb_file, now)
+                status = "ALIVE" if age <= max_age else "STALE"
+                if status == "STALE":
+                    all_alive = False
+                results.append((f"brain/{hb_file.name}", status, age))
+
+    # Print results
+    for name, status, age in results:
+        print(f"{name} {status} age:{age}s")
+
+    sys.exit(0 if all_alive else 1)
+
+
+def _get_age(hb_file, now):
+    """Extract epoch from first line and return age in seconds."""
+    try:
+        content = hb_file.read_text().strip().split('\n')
+        epoch_str = content[0].strip()
+        epoch = int(epoch_str)
+        age = int(now - epoch)
+        return max(0, age)
+    except (ValueError, IndexError):
+        return 99999
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    subparsers = parser.add_subparsers(dest="cmd")
+
+    beat_parser = subparsers.add_parser("beat", help="Write heartbeat")
+    beat_parser.add_argument("name", help="Heartbeat name")
+    beat_parser.add_argument("status", nargs="?", default=None, help="Optional status word")
+    beat_parser.add_argument("--state-dir", default=None, help="State directory (default: AESOP_STATE_ROOT or ./state)")
+    beat_parser.add_argument("--brain", action="store_true", help="Write to brain .heartbeats/ (overrides --state-dir)")
+
+    check_parser = subparsers.add_parser("check", help="Check heartbeat status")
+    check_parser.add_argument("--max-age", type=int, default=300, help="Max age in seconds (default 300)")
+    check_parser.add_argument("--state-dir", default=None, help="State directory (default: AESOP_STATE_ROOT or ./state)")
+
+    args = parser.parse_args()
+
+    if args.cmd == "beat":
+        state_dir = Path(args.state_dir) if args.state_dir else None
+        beat(args.name, args.status, state_dir=state_dir, brain=args.brain)
+    elif args.cmd == "check":
+        state_dir = Path(args.state_dir) if args.state_dir else None
+        check(args.max_age, state_dir=state_dir)
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()