@the-bearded-bear/claude-craft 3.0.3-next.d0d2746 → 3.1.0-next.a356bbd

package/Tools/Ralph/lib/checkpoint.sh

@@ -0,0 +1,238 @@
+#!/bin/bash
+# =============================================================================
+# Ralph Wiggum - Git Checkpointing Module
+# Creates git checkpoints for recovery and history tracking
+# =============================================================================
+
+# Checkpointing configuration
+CP_ENABLED="${CP_ENABLED:-true}"
+CP_ASYNC="${CP_ASYNC:-true}"
+CP_BRANCH_PREFIX="${CP_BRANCH_PREFIX:-ralph/}"
+CP_COMMIT_TEMPLATE="${CP_COMMIT_TEMPLATE:-checkpoint: Ralph iteration {iteration}}"
+
+# =============================================================================
+# Initialization
+# =============================================================================
+
+init_checkpointing() {
+    # Check if git is available
+    if ! command -v git &> /dev/null; then
+        CP_ENABLED=false
+        print_verbose "Git not found, checkpointing disabled"
+        return 1
+    fi
+
+    # Check if we're in a git repository
+    if ! git rev-parse --git-dir &> /dev/null; then
+        CP_ENABLED=false
+        print_verbose "Not in a git repository, checkpointing disabled"
+        return 1
+    fi
+
+    # Load config if available
+    if [[ -n "$CONFIG_FILE" && -f "$CONFIG_FILE" ]] && command -v yq &> /dev/null; then
+        local enabled=$(yq e '.checkpointing.enabled // ""' "$CONFIG_FILE" 2>/dev/null)
+        [[ "$enabled" == "false" ]] && CP_ENABLED=false
+
+        local async=$(yq e '.checkpointing.async // ""' "$CONFIG_FILE" 2>/dev/null)
+        [[ "$async" == "false" ]] && CP_ASYNC=false
+
+        local prefix=$(yq e '.checkpointing.branch_prefix // ""' "$CONFIG_FILE" 2>/dev/null)
+        [[ -n "$prefix" ]] && CP_BRANCH_PREFIX="$prefix"
+
+        local template=$(yq e '.checkpointing.commit_message_template // ""' "$CONFIG_FILE" 2>/dev/null)
+        [[ -n "$template" ]] && CP_COMMIT_TEMPLATE="$template"
+    fi
+
+    print_verbose "Checkpointing initialized:"
+    print_verbose "  - Enabled: $CP_ENABLED"
+    print_verbose "  - Async: $CP_ASYNC"
+    print_verbose "  - Branch prefix: $CP_BRANCH_PREFIX"
+
+    return 0
+}
+
+# =============================================================================
+# Create Checkpoint
+# =============================================================================
+
+create_checkpoint() {
+    local session_id="$1"
+    local iteration="$2"
+
+    if [[ "$CP_ENABLED" != "true" ]]; then
+        return 0
+    fi
+
+    # Check for changes to commit
+    if [[ -z "$(git status --porcelain 2>/dev/null)" ]]; then
+        print_verbose "No changes to checkpoint"
+        return 0
+    fi
+
+    # Generate commit message
+    local commit_msg="${CP_COMMIT_TEMPLATE/\{iteration\}/$iteration}"
+    commit_msg="${commit_msg/\{session_id\}/$session_id}"
+
+    if [[ "$CP_ASYNC" == "true" ]]; then
+        # Run checkpoint in background
+        _create_checkpoint_async "$session_id" "$iteration" "$commit_msg" &
+        print_verbose "${MSG_CHECKPOINT_CREATING} (async)"
+    else
+        # Run checkpoint synchronously
+        _create_checkpoint_sync "$session_id" "$iteration" "$commit_msg"
+    fi
+}
+
+# =============================================================================
+# Synchronous Checkpoint
+# =============================================================================
+
+_create_checkpoint_sync() {
+    local session_id="$1"
+    local iteration="$2"
+    local commit_msg="$3"
+
+    print_verbose "${MSG_CHECKPOINT_CREATING}"
+
+    # Stage all changes
+    git add -A 2>/dev/null
+
+    # Create commit
+    local commit_hash
+    commit_hash=$(git commit -m "$commit_msg" 2>/dev/null && git rev-parse --short HEAD)
+
+    if [[ -n "$commit_hash" ]]; then
+        print_verbose "${MSG_CHECKPOINT_CREATED}: $commit_hash"
+        log_session "$session_id" "INFO" "Checkpoint created: $commit_hash"
+    else
+        print_verbose "${MSG_CHECKPOINT_FAILED}"
+        log_session "$session_id" "WARN" "Checkpoint failed"
+    fi
+}
+
+# =============================================================================
+# Asynchronous Checkpoint
+# =============================================================================
+
+_create_checkpoint_async() {
+    local session_id="$1"
+    local iteration="$2"
+    local commit_msg="$3"
+
+    # Create a lock file to prevent concurrent checkpoints
+    local lock_file="/tmp/ralph-checkpoint-$session_id.lock"
+
+    # Try to acquire lock
+    if ! mkdir "$lock_file" 2>/dev/null; then
+        # Another checkpoint is in progress
+        return 0
+    fi
+
+    # Cleanup function
+    cleanup() {
+        rmdir "$lock_file" 2>/dev/null
+    }
+    trap cleanup EXIT
+
+    # Stage all changes
+    git add -A 2>/dev/null
+
+    # Create commit
+    git commit -m "$commit_msg" 2>/dev/null
+
+    # Log result
+    if [[ $? -eq 0 ]]; then
+        local commit_hash=$(git rev-parse --short HEAD 2>/dev/null)
+        log_session "$session_id" "INFO" "Async checkpoint created: $commit_hash"
+    fi
+
+    cleanup
+}
+
+# =============================================================================
+# Restore from Checkpoint
+# =============================================================================
+
+restore_checkpoint() {
+    local session_id="$1"
+    local commit_hash="$2"
+
+    if [[ "$CP_ENABLED" != "true" ]]; then
+        print_error "Checkpointing is disabled"
+        return 1
+    fi
+
+    print_info "${MSG_CHECKPOINT_RESTORING}"
+
+    # Verify commit exists
+    if ! git cat-file -e "$commit_hash" 2>/dev/null; then
+        print_error "Commit not found: $commit_hash"
+        return 1
+    fi
+
+    # Create a backup branch of current state
+    local backup_branch="ralph-backup-$(date +%s)"
+    git branch "$backup_branch" 2>/dev/null
+
+    # Reset to the checkpoint
+    if git reset --hard "$commit_hash" 2>/dev/null; then
+        print_success "${MSG_CHECKPOINT_RESTORED}"
+        log_session "$session_id" "INFO" "Restored to checkpoint: $commit_hash (backup: $backup_branch)"
+        return 0
+    else
+        print_error "${MSG_CHECKPOINT_FAILED}"
+        return 1
+    fi
+}
+
+# =============================================================================
+# List Checkpoints
+# =============================================================================
+
+list_checkpoints() {
+    local session_id="$1"
+
+    if [[ "$CP_ENABLED" != "true" ]]; then
+        echo "[]"
+        return
+    fi
+
+    # Find commits matching the checkpoint pattern
+    local commits
+    commits=$(git log --oneline --grep="checkpoint: Ralph" 2>/dev/null | head -20)
+
+    if [[ -n "$commits" ]]; then
+        echo "$commits" | while read -r line; do
+            local hash=$(echo "$line" | cut -d' ' -f1)
+            local msg=$(echo "$line" | cut -d' ' -f2-)
+            echo "{\"hash\":\"$hash\",\"message\":\"$msg\"}"
+        done | jq -s '.'
+    else
+        echo "[]"
+    fi
+}
+
+# =============================================================================
+# Create Branch for Session
+# =============================================================================
+
+create_session_branch() {
+    local session_id="$1"
+    local branch_name="${CP_BRANCH_PREFIX}${session_id}"
+
+    if [[ "$CP_ENABLED" != "true" ]]; then
+        return 1
+    fi
+
+    # Check if branch already exists
+    if git show-ref --verify --quiet "refs/heads/$branch_name" 2>/dev/null; then
+        # Switch to existing branch
+        git checkout "$branch_name" 2>/dev/null
+    else
+        # Create new branch
+        git checkout -b "$branch_name" 2>/dev/null
+    fi
+
+    print_verbose "${MSG_CHECKPOINT_BRANCH}: $branch_name"
+}

package/Tools/Ralph/lib/circuit-breaker.sh

@@ -0,0 +1,172 @@
+#!/bin/bash
+# =============================================================================
+# Ralph Wiggum - Circuit Breaker Module
+# Safety mechanism to prevent infinite loops and detect stalls
+# =============================================================================
+
+# Circuit breaker thresholds (defaults)
+CB_NO_CHANGES_THRESHOLD="${CB_NO_CHANGES_THRESHOLD:-3}"
+CB_REPEATED_ERROR_THRESHOLD="${CB_REPEATED_ERROR_THRESHOLD:-5}"
+CB_OUTPUT_DECLINE_THRESHOLD="${CB_OUTPUT_DECLINE_THRESHOLD:-70}"
+
+# Circuit breaker state
+CB_ITERATIONS_WITHOUT_CHANGES=0
+CB_CONSECUTIVE_ERRORS=0
+CB_PEAK_OUTPUT_LENGTH=0
+CB_LAST_OUTPUT_LENGTH=0
+CB_TRIGGERED=false
+CB_TRIGGER_REASON=""
+
+# =============================================================================
+# Initialization
+# =============================================================================
+
+init_circuit_breaker() {
+    CB_ITERATIONS_WITHOUT_CHANGES=0
+    CB_CONSECUTIVE_ERRORS=0
+    CB_PEAK_OUTPUT_LENGTH=0
+    CB_LAST_OUTPUT_LENGTH=0
+    CB_TRIGGERED=false
+    CB_TRIGGER_REASON=""
+
+    # Load thresholds from config if available
+    if [[ -n "$CONFIG_FILE" && -f "$CONFIG_FILE" ]] && command -v yq &> /dev/null; then
+        local no_changes=$(yq e '.circuit_breaker.no_file_changes_threshold // ""' "$CONFIG_FILE" 2>/dev/null)
+        [[ -n "$no_changes" ]] && CB_NO_CHANGES_THRESHOLD=$no_changes
+
+        local errors=$(yq e '.circuit_breaker.repeated_error_threshold // ""' "$CONFIG_FILE" 2>/dev/null)
+        [[ -n "$errors" ]] && CB_REPEATED_ERROR_THRESHOLD=$errors
+
+        local decline=$(yq e '.circuit_breaker.output_decline_threshold // ""' "$CONFIG_FILE" 2>/dev/null)
+        [[ -n "$decline" ]] && CB_OUTPUT_DECLINE_THRESHOLD=$decline
+    fi
+
+    print_verbose "Circuit breaker initialized:"
+    print_verbose "  - No changes threshold: $CB_NO_CHANGES_THRESHOLD"
+    print_verbose "  - Error threshold: $CB_REPEATED_ERROR_THRESHOLD"
+    print_verbose "  - Output decline threshold: ${CB_OUTPUT_DECLINE_THRESHOLD}%"
+}
+
+# =============================================================================
+# Circuit Breaker Check
+# =============================================================================
+
+check_circuit_breaker() {
+    # Return 0 (true) if triggered, 1 (false) if OK to continue
+
+    # Check no progress (no file changes)
+    if [[ $CB_ITERATIONS_WITHOUT_CHANGES -ge $CB_NO_CHANGES_THRESHOLD ]]; then
+        CB_TRIGGERED=true
+        CB_TRIGGER_REASON="no_progress"
+        print_warning "${MSG_CB_TRIGGERED}: ${MSG_CB_NO_CHANGES} $CB_ITERATIONS_WITHOUT_CHANGES ${MSG_CB_ITERATIONS}"
+        return 0
+    fi
+
+    # Check repeated errors
+    if [[ $CB_CONSECUTIVE_ERRORS -ge $CB_REPEATED_ERROR_THRESHOLD ]]; then
+        CB_TRIGGERED=true
+        CB_TRIGGER_REASON="repeated_errors"
+        print_warning "${MSG_CB_TRIGGERED}: ${MSG_CB_REPEATED_ERRORS}"
+        return 0
+    fi
+
+    # Check output decline
+    if [[ $CB_PEAK_OUTPUT_LENGTH -gt 0 && $CB_LAST_OUTPUT_LENGTH -gt 0 ]]; then
+        local decline_percent=$(( (CB_PEAK_OUTPUT_LENGTH - CB_LAST_OUTPUT_LENGTH) * 100 / CB_PEAK_OUTPUT_LENGTH ))
+        if [[ $decline_percent -ge $CB_OUTPUT_DECLINE_THRESHOLD ]]; then
+            CB_TRIGGERED=true
+            CB_TRIGGER_REASON="output_decline"
+            print_warning "${MSG_CB_TRIGGERED}: ${MSG_CB_OUTPUT_DECLINE} ${decline_percent}${MSG_CB_PERCENT}"
+            return 0
+        fi
+    fi
+
+    return 1
+}
+
+# =============================================================================
+# Update Circuit Breaker State
+# =============================================================================
+
+update_circuit_breaker() {
+    local event_type="$1"
+    local output="$2"
+
+    case "$event_type" in
+        progress)
+            # Reset counters on progress
+            CB_ITERATIONS_WITHOUT_CHANGES=0
+            CB_CONSECUTIVE_ERRORS=0
+
+            # Update output tracking
+            local output_length=${#output}
+            CB_LAST_OUTPUT_LENGTH=$output_length
+            if [[ $output_length -gt $CB_PEAK_OUTPUT_LENGTH ]]; then
+                CB_PEAK_OUTPUT_LENGTH=$output_length
+            fi
+            ;;
+
+        no_progress)
+            CB_ITERATIONS_WITHOUT_CHANGES=$((CB_ITERATIONS_WITHOUT_CHANGES + 1))
+            print_verbose "No progress: $CB_ITERATIONS_WITHOUT_CHANGES / $CB_NO_CHANGES_THRESHOLD"
+            ;;
+
+        error)
+            CB_CONSECUTIVE_ERRORS=$((CB_CONSECUTIVE_ERRORS + 1))
+            print_verbose "Error count: $CB_CONSECUTIVE_ERRORS / $CB_REPEATED_ERROR_THRESHOLD"
+            ;;
+
+        reset)
+            CB_ITERATIONS_WITHOUT_CHANGES=0
+            CB_CONSECUTIVE_ERRORS=0
+            CB_TRIGGERED=false
+            CB_TRIGGER_REASON=""
+            print_verbose "${MSG_CB_RESET}"
+            ;;
+    esac
+
+    # Update session state if available
+    if [[ -n "$SESSION_ID" ]]; then
+        update_session_state "$SESSION_ID" "circuit_breaker" "{
+            \"iterations_without_changes\": $CB_ITERATIONS_WITHOUT_CHANGES,
+            \"consecutive_errors\": $CB_CONSECUTIVE_ERRORS,
+            \"peak_output_length\": $CB_PEAK_OUTPUT_LENGTH,
+            \"last_output_length\": $CB_LAST_OUTPUT_LENGTH,
+            \"triggered\": $CB_TRIGGERED,
+            \"trigger_reason\": \"$CB_TRIGGER_REASON\"
+        }"
+    fi
+}
+
+# =============================================================================
+# Circuit Breaker Status
+# =============================================================================
+
+get_circuit_breaker_status() {
+    cat <<EOF
+{
+    "iterations_without_changes": $CB_ITERATIONS_WITHOUT_CHANGES,
+    "consecutive_errors": $CB_CONSECUTIVE_ERRORS,
+    "peak_output_length": $CB_PEAK_OUTPUT_LENGTH,
+    "last_output_length": $CB_LAST_OUTPUT_LENGTH,
+    "triggered": $CB_TRIGGERED,
+    "trigger_reason": "$CB_TRIGGER_REASON",
+    "thresholds": {
+        "no_changes": $CB_NO_CHANGES_THRESHOLD,
+        "errors": $CB_REPEATED_ERROR_THRESHOLD,
+        "output_decline": $CB_OUTPUT_DECLINE_THRESHOLD
+    }
+}
+EOF
+}
+
+# =============================================================================
+# Force Trip
+# =============================================================================
+
+trip_circuit_breaker() {
+    local reason="$1"
+    CB_TRIGGERED=true
+    CB_TRIGGER_REASON="${reason:-manual}"
+    print_warning "${MSG_CB_TRIGGERED}: $CB_TRIGGER_REASON"
+}