ralph/

loop_runner.rs

use crate::compaction;
use crate::config::Config;
use crate::errors::{RalphError, Result};
use crate::memory::MemoryStore;
use crate::output::{Phase, Printer};
use crate::providers::{ContentPart, LlmProvider, Message, MessageContent, Role};
use crate::session::{Session, SessionStatus};
use crate::tools::{
    execute_read_only, is_read_only, search_tools::search_available, shell_tools, tool_defs,
    ReadOnlyContext, ToolCall, ToolRegistry, ToolResult,
};
use indicatif::{ProgressBar, ProgressStyle};
use std::path::PathBuf;
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::{Arc, Mutex};
use std::time::Duration;

pub struct LoopRunner {
    normal_provider: Arc<dyn LlmProvider>,
    /// Optional reasoning (extended thinking) provider used on turn 1 and after failures.
    reasoning_provider: Option<Arc<dyn LlmProvider>>,
    config: Config,
    workspace: PathBuf,
    printer: Arc<Printer>,
    /// None = unlimited turns (interactive mode).
    max_turns: Option<u32>,
    dry_run: bool,
    no_confirm: bool,
    /// When true, skip the automatic `pip install -e .` / `npm install` etc.
    /// that would normally run before the first LLM turn.
    skip_workspace_setup: bool,
    memory: Arc<Mutex<MemoryStore>>,
    /// Languages to activate LSP for (one client per language).
    lsp_languages: Vec<String>,
    /// Shared flag: when true, show diff + confirm before every write_file.
    diff_preview: Arc<AtomicBool>,
    /// Shared flag: when true, expose PR/CI tools to the LLM.
    pr_enabled: Arc<AtomicBool>,
}

impl LoopRunner {
    pub fn new(
        normal_provider: Arc<dyn LlmProvider>,
        reasoning_provider: Option<Arc<dyn LlmProvider>>,
        config: Config,
        workspace: PathBuf,
        printer: Arc<Printer>,
        max_turns: Option<u32>,
        dry_run: bool,
        no_confirm: bool,
        skip_workspace_setup: bool,
        memory: Arc<Mutex<MemoryStore>>,
        lsp_languages: Vec<String>,
        diff_preview: Arc<AtomicBool>,
        pr_enabled: Arc<AtomicBool>,
    ) -> Self {
        Self {
            normal_provider,
            reasoning_provider,
            config,
            workspace,
            printer,
            max_turns,
            dry_run,
            no_confirm,
            skip_workspace_setup,
            memory,
            lsp_languages,
            diff_preview,
            pr_enabled,
        }
    }

    pub async fn run(
        &self,
        prompt: &str,
        session: &mut Session,
        cancelled: Arc<AtomicBool>,
    ) -> Result<()> {
        let search_on = search_available(
            &self.config.search.brave_api_key_env,
            &self.config.search.serp_api_key_env,
        );
        let pr_on = self.pr_enabled.load(Ordering::Relaxed);
        let tool_defs = tool_defs(search_on, pr_on);

        // Compute tool schema overhead once — these tokens are sent with every
        // API request but are not in session.messages, so they must be added to
        // the threshold check to avoid hitting the context limit unexpectedly.
        let tool_overhead_tokens = {
            let json = serde_json::to_string(&tool_defs).unwrap_or_default();
            compaction::count_tokens(&json)
        };

        if search_on {
            self.printer.print(Phase::Ralph, "Web search enabled.");
        } else {
            self.printer.print(
                Phase::Ralph,
                "Web search unavailable (set BRAVE_API_KEY or SERP_API_KEY to enable).",
            );
        }

        let mut tools = ToolRegistry::new(
            self.workspace.clone(),
            self.config.clone(),
            Arc::clone(&self.printer),
            self.no_confirm,
            Arc::clone(&self.memory),
            self.lsp_languages.clone(),
            Arc::clone(&self.diff_preview),
        );

        session.log_event(&format!("Session started. Prompt: {}", prompt));

        // Install project dependencies before the first LLM turn so the agent
        // can run tests and builds without needing to set up the environment itself.
        // Skipped when --no-setup is passed (e.g. by the benchmark harness which
        // manages its own isolated venv).
        if !self.skip_workspace_setup {
            install_workspace_deps(&self.workspace, &self.printer).await;
        }

        session.messages.push(Message::user(prompt));
        if let Err(e) = session.flush() {
            self.printer
                .print_error(&format!("Warning: failed to persist session: {}", e));
        }

        let auto_test_cmd = self.config.testing.resolved_cmd(&self.workspace);

        let mut turn: u32 = 0;
        let mut test_fail_count: u32 = 0;
        // How many times we've nudged the LLM to stop planning and use tools.
        // Capped at 5 to prevent infinite nudge loops.
        let mut plan_nudge_count: u32 = 0;
        // Consecutive turns without any file modification.
        let mut turns_since_edit: u32 = 0;
        // How many stall nudges have fired (reset on edit, exit after 3).
        let mut stall_nudge_count: u32 = 0;
        // Two-provider: use reasoning provider on turn 1 and after test failures.
        let mut next_turn_uses_reasoning: bool = true; // turn 1 always uses reasoning
                                                       // Token accumulators for the session.
        let mut total_input_tokens: u64 = 0;
        let mut total_output_tokens: u64 = 0;
        let mut total_reasoning_tokens: u64 = 0;
        // Track last-read turn per file path for duplicate eviction.
        let mut file_last_read: std::collections::HashMap<String, u32> =
            std::collections::HashMap::new();
        // Track files that were edited (so we don't evict their next full read).
        let mut files_edited_since_read: std::collections::HashSet<String> =
            std::collections::HashSet::new();
        // Consecutive edit_file failures (old_string not found) → trigger reasoning.
        let mut consecutive_edit_failures: u32 = 0;
        // Consecutive run_test failures (tests not passing) → trigger reasoning.
        let mut consecutive_test_failures: u32 = 0;
        // Per-turn action category: "read", "edit", "test", "cmd" — rolling window of last 5.
        let mut recent_action_categories: std::collections::VecDeque<&'static str> =
            std::collections::VecDeque::with_capacity(5);
        loop {
            turn += 1;

            // Check for user cancellation between turns
            if cancelled.load(Ordering::Relaxed) {
                self.printer.print(Phase::Ralph, "Task interrupted.");
                session.log_event("Task interrupted by user");
                session.set_status(SessionStatus::Interrupted).ok();
                return Err(RalphError::Interrupted);
            }

            // Enforce optional turn limit
            if let Some(max) = self.max_turns {
                if turn > max {
                    self.printer.print(
                        Phase::Failed,
                        &format!("Reached max turns ({}). Task incomplete.", max),
                    );
                    session.log_event(&format!("Max turns ({}) reached", max));
                    session.set_status(SessionStatus::Interrupted).ok();
                    return Err(RalphError::MaxTurnsReached(max));
                }
            }

            let turn_label = match self.max_turns {
                Some(max) => format!("Turn {}/{}", turn, max),
                None => format!("Turn {}", turn),
            };
            self.printer.print(Phase::Observe, &turn_label);
            session.log_event(&format!("--- Turn {} ---", turn));

            // ── OBSERVE: compact if needed ─────────────────────────────────────
            if self.config.compaction.enabled
                && compaction::should_compact(
                    &session.messages,
                    self.config.compaction.compact_at_tokens,
                    tool_overhead_tokens,
                )
            {
                self.printer
                    .print(Phase::Compact, "Context approaching limit — compacting...");
                session.log_event("Compacting context");

                let keep = self.config.compaction.keep_recent_turns;
                let compact_to = self.config.compaction.compact_to_tokens;

                let result = compaction::compact(
                    &session.messages,
                    self.normal_provider.as_ref(),
                    keep,
                    compact_to,
                )
                .await;

                let result = match result {
                    Ok(r) => Ok(r),
                    Err(e) => {
                        self.printer.print(
                            Phase::Compact,
                            &format!(
                                "Primary compaction failed ({}), retrying with split compaction...",
                                e
                            ),
                        );
                        session.log_event(&format!(
                            "Primary compaction failed: {e}. Trying split compaction."
                        ));
                        compaction::compact_split(
                            &session.messages,
                            self.normal_provider.as_ref(),
                            keep,
                            compact_to,
                        )
                        .await
                    }
                };

                match result {
                    Ok((new_window, archive)) => {
                        compaction::archive(&session.session_dir, &archive).ok();
                        session.messages = new_window;
                        self.printer.print(Phase::Compact, "Compaction complete.");
                        session.log_event("Compaction complete");
                    }
                    Err(e) => {
                        self.printer
                            .print_error(&format!("Compaction failed: {}", e));
                        session.log_event(&format!("Compaction failed: {}", e));
                    }
                }
            }

            // ── PLAN: select provider and call LLM ────────────────────────────
            let active_provider: &Arc<dyn LlmProvider> = if next_turn_uses_reasoning {
                self.reasoning_provider
                    .as_ref()
                    .unwrap_or(&self.normal_provider)
            } else {
                &self.normal_provider
            };
            // Reset for next turn — will be set again if a test failure is seen.
            next_turn_uses_reasoning = false;

            let was_streamed;
            let llm_response = if active_provider.supports_streaming() {
                was_streamed = true;
                self.printer.print_streaming_start();
                let (tx, mut rx) = tokio::sync::mpsc::unbounded_channel::<String>();
                let provider_clone = Arc::clone(active_provider);
                let messages_snap = session.messages.clone();
                let tools_snap = tool_defs.clone();

                let task = tokio::spawn(async move {
                    provider_clone
                        .chat_streaming(&messages_snap, &tools_snap, &tx)
                        .await
                });

                while let Some(token) = rx.recv().await {
                    self.printer.print_streaming_token(&token);
                }
                self.printer.print_streaming_end();

                match task.await {
                    Ok(Ok(r)) => r,
                    Ok(Err(e)) => {
                        self.printer.print_error(&format!("LLM error: {}", e));
                        session.log_event(&format!("LLM error: {}", e));
                        session.set_status(SessionStatus::Failed).ok();
                        return Err(e);
                    }
                    Err(e) => {
                        let err = RalphError::ToolFailed {
                            tool: "llm".to_string(),
                            message: e.to_string(),
                        };
                        self.printer.print_error(&format!("LLM task error: {}", e));
                        session.set_status(SessionStatus::Failed).ok();
                        return Err(err);
                    }
                }
            } else {
                was_streamed = false;
                self.printer.print(Phase::Plan, "Calling LLM...");
                let spinner =
                    make_spinner(&format!("  Waiting for {} ...", active_provider.name()));
                match active_provider.chat(&session.messages, &tool_defs).await {
                    Ok(r) => {
                        spinner.finish_and_clear();
                        r
                    }
                    Err(e) => {
                        spinner.finish_and_clear();
                        self.printer.print_error(&format!("LLM error: {}", e));
                        session.log_event(&format!("LLM error: {}", e));
                        session.set_status(SessionStatus::Failed).ok();
                        return Err(e);
                    }
                }
            };

            // ── Token usage per turn ────────────────────────────────────────────
            total_input_tokens += llm_response.input_tokens;
            total_output_tokens += llm_response.output_tokens;
            total_reasoning_tokens += llm_response.reasoning_tokens;
            self.printer.print(
                Phase::Observe,
                &format!(
                    "[tokens] in={} out={} reasoning={}",
                    llm_response.input_tokens,
                    llm_response.output_tokens,
                    llm_response.reasoning_tokens
                ),
            );

            session.log_event(&format!(
                "LLM responded: {} tool calls, {} tokens",
                llm_response.tool_calls.len(),
                llm_response.tokens_used
            ));

            if llm_response.tool_calls.is_empty() {
                let text = llm_response
                    .text
                    .as_deref()
                    .unwrap_or("")
                    .trim()
                    .to_string();

                if !text.is_empty() {
                    // Skip reprint when the tokens were already output live via streaming.
                    if !was_streamed {
                        self.printer.print(Phase::Plan, &text);
                    }
                    let mut msg = Message::assistant(text.clone());
                    msg.reasoning_content = llm_response.reasoning_content.clone();
                    session.messages.push(msg);
                }

                // Two cases where we nudge instead of completing:
                //
                // A) Empty response — LLM returned nothing. Usually means it is
                //    stuck (e.g. couldn't read a large file) and gave up silently.
                //    Push it to try a different approach.
                //
                // B) Plan-without-execution — LLM described the fix in prose but
                //    called no tool. Push it to actually make the edit.
                //
                // Both are capped at 5 nudges to prevent infinite loops.
                let is_empty_response = text.is_empty();
                let is_plan = looks_like_unexecuted_plan(&text);

                if (is_empty_response || is_plan) && plan_nudge_count < 5 {
                    plan_nudge_count += 1;
                    let nudge = if is_empty_response {
                        "Your last response was empty. You MUST call a tool in your next \
                         response — for example `list_dir` or `read_file` to explore the repo, \
                         or `edit_file` / `write_file` to apply your fix. Do NOT reply with \
                         only text. Start by calling `list_dir` with path \".\" if you are \
                         unsure where to begin."
                    } else {
                        "You described what needs to be done but did not call any tool. \
                         You MUST call a tool in your next response — call `edit_file` or \
                         `write_file` to apply the fix right now. Do not describe it again; \
                         just do it. If you are not sure of the exact text to replace, call \
                         `read_file` first to see the current file content."
                    };
                    self.printer.print(
                        Phase::Verify,
                        &format!(
                            "[nudge {}/5] ({})",
                            plan_nudge_count,
                            if is_empty_response {
                                "empty response"
                            } else {
                                "plan without execution"
                            }
                        ),
                    );
                    session.log_event(&format!(
                        "Nudge {}/5: {}",
                        plan_nudge_count,
                        if is_empty_response {
                            "empty response"
                        } else {
                            "plan without execution"
                        }
                    ));
                    session.messages.push(Message::user(nudge));
                    continue;
                }

                self.printer
                    .print(Phase::Done, "Task complete (no further actions requested).");
                session.log_event("Task complete");
                session.set_status(SessionStatus::Done).ok();
                self.printer.print(
                    Phase::Ralph,
                    &format!(
                        "[tokens total] in={} out={} reasoning={}",
                        total_input_tokens, total_output_tokens, total_reasoning_tokens
                    ),
                );
                return Ok(());
            }

            // LLM called at least one tool — reset the plan nudge counter.
            plan_nudge_count = 0;

            // Tool calls present — store the assistant message with tool-use parts so
            // that OpenAI/DeepSeek see a valid "tool_calls" → "tool" message sequence.
            {
                let mut parts: Vec<ContentPart> = Vec::new();
                if let Some(ref text) = llm_response.text {
                    if !text.is_empty() {
                        // Skip reprint when the tokens were already output live via streaming.
                        if !was_streamed {
                            self.printer.print(Phase::Plan, text);
                        }
                        parts.push(ContentPart::Text { text: text.clone() });
                    }
                }
                for tc in &llm_response.tool_calls {
                    parts.push(ContentPart::ToolUse {
                        id: tc.id.clone(),
                        name: tc.name.clone(),
                        input: tc.arguments.clone(),
                    });
                }
                session.messages.push(Message {
                    role: Role::Assistant,
                    content: MessageContent::Parts(parts),
                    tool_call_id: None,
                    name: None,
                    reasoning_content: llm_response.reasoning_content.clone(),
                });
            }

            // ── EXECUTE ────────────────────────────────────────────────────────
            let pre_turn_file_count = tools.modified_files.len();
            let mut tool_results: Vec<ToolResult> = Vec::new();
            let mut done = false;
            let mut failed = false;
            let mut final_message = String::new();

            // Find the leading run of read-only tool calls.  Only worth
            // spawning tasks when there are 2 or more — a single call has
            // no parallelism benefit and dry-run never executes anyway.
            let parallel_n = if self.dry_run {
                0
            } else {
                let n = llm_response
                    .tool_calls
                    .iter()
                    .take_while(|tc| is_read_only(&tc.name))
                    .count();
                if n >= 2 {
                    n
                } else {
                    0
                }
            };

            // ── Parallel read-only batch ────────────────────────────────────────
            if parallel_n >= 2 {
                let read_batch = &llm_response.tool_calls[..parallel_n];
                self.printer.print(
                    Phase::Tool,
                    &format!("Running {} read operations in parallel...", parallel_n),
                );

                let ctx = Arc::new(ReadOnlyContext {
                    workspace: self.workspace.clone(),
                    config: self.config.clone(),
                    printer: Arc::clone(&self.printer),
                    symbol_index: Arc::new(tokio::sync::Mutex::new(None)),
                    memory: Arc::clone(&self.memory),
                });

                let tasks: Vec<_> = read_batch
                    .iter()
                    .map(|tc| {
                        session.log_event(&format!(
                            "Tool call (parallel): {} {:?}",
                            tc.name, tc.arguments
                        ));
                        let ctx2 = Arc::clone(&ctx);
                        let call = ToolCall {
                            id: tc.id.clone(),
                            name: tc.name.clone(),
                            arguments: tc.arguments.clone(),
                        };
                        tokio::spawn(execute_read_only(ctx2, call))
                    })
                    .collect();

                for (i, task) in tasks.into_iter().enumerate() {
                    let tc = &read_batch[i];
                    let display = describe_tool_call(&tc.name, &tc.arguments);
                    let result = match task.await {
                        Ok(Ok(r)) => {
                            self.printer.print_tool_call(&tc.name, &display, &r.output);
                            session.log_event(&format!(
                                "Tool result: {} → {}",
                                tc.name,
                                truncate_log(&r.output, 200)
                            ));
                            r
                        }
                        Ok(Err(e)) => {
                            self.printer.print_error(&e.to_string());
                            session.log_event(&format!("Tool {} error: {}", tc.name, e));
                            ToolResult {
                                call_id: tc.id.clone(),
                                tool_name: tc.name.clone(),
                                output: format!("ERROR: {}", e),
                                is_error: true,
                            }
                        }
                        Err(e) => ToolResult {
                            call_id: tc.id.clone(),
                            tool_name: tc.name.clone(),
                            output: format!("ERROR: task panicked: {}", e),
                            is_error: true,
                        },
                    };
                    tool_results.push(result);
                }
            }

            // ── Sequential calls (remaining after any parallel batch) ────────────
            for tc in &llm_response.tool_calls[parallel_n..] {
                let tool_call = ToolCall {
                    id: tc.id.clone(),
                    name: tc.name.clone(),
                    arguments: tc.arguments.clone(),
                };

                let display = describe_tool_call(&tc.name, &tc.arguments);
                session.log_event(&format!("Tool call: {} {:?}", tc.name, tc.arguments));

                if self.dry_run {
                    self.printer
                        .print(Phase::Tool, "[dry-run] Skipping execution.");
                    tool_results.push(ToolResult {
                        call_id: tc.id.clone(),
                        tool_name: tc.name.clone(),
                        output: "[dry-run] Not executed.".to_string(),
                        is_error: false,
                    });
                    continue;
                }

                match tools.execute(&tool_call).await {
                    Ok(result) => {
                        self.printer
                            .print_tool_call(&tc.name, &display, &result.output);
                        session.log_event(&format!(
                            "Tool result: {} → {}",
                            tc.name,
                            truncate_log(&result.output, 200)
                        ));

                        if result.output.starts_with("DONE:") {
                            done = true;
                            final_message = result.output[5..].trim().to_string();
                        } else if result.output.starts_with("FAILED:") {
                            failed = true;
                            final_message = result.output[7..].trim().to_string();
                        }

                        tool_results.push(result);
                    }
                    Err(RalphError::UserAborted) => {
                        self.printer
                            .print(Phase::Ralph, "Action cancelled by user.");
                        session.log_event(&format!("Tool {} cancelled by user", tc.name));
                        tool_results.push(ToolResult {
                            call_id: tc.id.clone(),
                            tool_name: tc.name.clone(),
                            output: "Cancelled by user.".to_string(),
                            is_error: false,
                        });
                    }
                    Err(e) => {
                        let err_msg = e.to_string();
                        self.printer.print_error(&err_msg);
                        session.log_event(&format!("Tool {} error: {}", tc.name, err_msg));
                        tool_results.push(ToolResult {
                            call_id: tc.id.clone(),
                            tool_name: tc.name.clone(),
                            output: format!("ERROR: {}", err_msg),
                            is_error: true,
                        });
                    }
                }
            }

            // Sync modified files to session
            for path in &tools.modified_files {
                if !session.modified_files.contains(path) {
                    session.modified_files.push(path.clone());
                }
            }

            // ── TRACK ACTION CATEGORIES & EDIT FAILURES ───────────────────────
            {
                let mut this_turn_category: &'static str = "read";
                let mut had_edit_failure = false;
                let mut had_successful_edit = false;
                let mut had_test_call = false;

                for result in &tool_results {
                    match result.tool_name.as_str() {
                        "edit_file" | "edit_file_multi" | "write_file" | "delete_file" => {
                            if result.is_error {
                                had_edit_failure = true;
                            } else {
                                had_successful_edit = true;
                            }
                            this_turn_category = "edit";
                        }
                        "run_test" | "run_build" => {
                            had_test_call = true;
                            if this_turn_category != "edit" {
                                this_turn_category = "test";
                            }
                        }
                        "run_command" => {
                            if this_turn_category == "read" {
                                this_turn_category = "cmd";
                            }
                        }
                        _ => {}
                    }
                }

                // Update edit failure streak.
                if had_edit_failure && !had_successful_edit {
                    consecutive_edit_failures += 1;
                } else if had_successful_edit {
                    consecutive_edit_failures = 0;
                }

                // Update test failure streak.
                if had_test_call {
                    let any_test_failure = tool_results
                        .iter()
                        .filter(|r| r.tool_name == "run_test" || r.tool_name == "run_build")
                        .any(|r| !test_passed(&r.output));
                    if any_test_failure {
                        consecutive_test_failures += 1;
                    } else {
                        consecutive_test_failures = 0;
                    }
                }

                // Adaptive reasoning: trigger after repeated edit failures or test failures.
                if consecutive_edit_failures >= 3 || consecutive_test_failures >= 2 {
                    if !next_turn_uses_reasoning {
                        self.printer.print(
                            Phase::Verify,
                            &format!(
                                "[reasoning] Activating reasoning provider (edit_failures={}, test_failures={}).",
                                consecutive_edit_failures, consecutive_test_failures
                            ),
                        );
                    }
                    next_turn_uses_reasoning = true;
                }

                // Update rolling action window (max 5).
                if recent_action_categories.len() >= 5 {
                    recent_action_categories.pop_front();
                }
                recent_action_categories.push_back(this_turn_category);
            }

            // ── ANALYSIS SPIRAL DETECTION ──────────────────────────────────────
            // Track stall here but inject the nudge AFTER tool results are appended
            // below.  Injecting before tool results would put a user message between
            // the assistant "tool_calls" message and its required tool results, which
            // DeepSeek/OpenAI reject with HTTP 400.
            let files_changed_this_turn = tools.modified_files.len() > pre_turn_file_count;
            let stall_nudge: Option<String> = if files_changed_this_turn {
                turns_since_edit = 0;
                stall_nudge_count = 0;
                // Mark edited files so their next read shows full content.
                for path in tools.modified_files.iter().skip(pre_turn_file_count) {
                    let key = path.to_string_lossy().to_string();
                    files_edited_since_read.insert(key);
                }
                None
            } else {
                turns_since_edit += 1;
                if turns_since_edit > 0 && turns_since_edit % 20 == 0 {
                    stall_nudge_count += 1;
                    if stall_nudge_count >= 3 {
                        // Exit the loop — too many stall nudges with no progress.
                        self.printer.print(
                            Phase::Verify,
                            "[stall] No edits after 3 stall nudges — exiting.",
                        );
                        session.log_event("[stall] No edits after 3 stall nudges — exiting.");
                        session.set_status(SessionStatus::Interrupted).ok();
                        // Print token totals before exiting
                        self.printer.print(
                            Phase::Ralph,
                            &format!(
                                "[tokens total] in={} out={} reasoning={}",
                                total_input_tokens, total_output_tokens, total_reasoning_tokens
                            ),
                        );
                        return Err(RalphError::ToolFailed {
                            tool: "stall_exit".to_string(),
                            message: "[stall] No edits after 3 stall nudges — exiting.".to_string(),
                        });
                    }
                    self.printer.print(
                        Phase::Verify,
                        &format!(
                            "[stall] No edits for {} turns — prompting to act (nudge {}/3).",
                            turns_since_edit, stall_nudge_count
                        ),
                    );
                    session.log_event(&format!(
                        "Analysis stall detected (nudge {}/3) — injecting action prompt",
                        stall_nudge_count
                    ));
                    Some(context_aware_stall_nudge(
                        turns_since_edit,
                        &recent_action_categories,
                        consecutive_test_failures,
                    ))
                } else {
                    None
                }
            };

            // Check for test failures in tool results to set reasoning provider for next turn.
            // (Adaptive reasoning from edit failures is handled in the action-tracking block above.)
            for result in &tool_results {
                let out = &result.output;
                if result.tool_name == "run_test" || result.tool_name == "run_build" {
                    if !test_passed(out) {
                        next_turn_uses_reasoning = true;
                    }
                }
            }

            // Append tool results to messages with post-processing.
            const MAX_TOOL_OUTPUT_CHARS: usize = 8_000; // ~2k tokens
            const MAX_TEST_OUTPUT_CHARS: usize = 3_000; // ~750 tokens for test output
            for result in &tool_results {
                let stored = post_process_tool_output(
                    result,
                    MAX_TOOL_OUTPUT_CHARS,
                    MAX_TEST_OUTPUT_CHARS,
                    turn,
                    &mut file_last_read,
                    &files_edited_since_read,
                );
                session.messages.push(Message::tool_result(
                    &result.call_id,
                    &result.tool_name,
                    &stored,
                ));
            }

            // Inject stall nudge AFTER tool results so the message order is valid:
            // [assistant tool_calls] → [tool results] → [user stall nudge]
            if let Some(ref msg) = stall_nudge {
                session.messages.push(Message::user(msg.as_str()));
            }

            if let Err(e) = session.save_turn(&[], turn) {
                self.printer
                    .print_error(&format!("Warning: failed to save turn: {}", e));
            }

            // ── AUTO-TEST ──────────────────────────────────────────────────────
            // Run the project test suite automatically if:
            //   • auto_test is configured for this workspace
            //   • files were modified this turn
            //   • Ralph did not already call run_test itself
            if let Some(ref cmd) = auto_test_cmd {
                let files_modified = tools.modified_files.len() > pre_turn_file_count;
                let test_called = llm_response
                    .tool_calls
                    .iter()
                    .any(|tc| tc.name == "run_test");

                if files_modified && !test_called {
                    self.printer
                        .print(Phase::Verify, &format!("Auto-test: {}", cmd));
                    session.log_event(&format!("Auto-test: {}", cmd));

                    match shell_tools::run_command(cmd, &self.workspace).await {
                        Ok(output) => {
                            session.log_event(&format!(
                                "Auto-test result: {}",
                                truncate_log(&output, 200)
                            ));

                            if test_passed(&output) {
                                self.printer.print(Phase::Verify, "Tests passed.");
                                test_fail_count = 0;
                            } else {
                                test_fail_count += 1;
                                self.printer.print(
                                    Phase::Verify,
                                    &format!(
                                        "Tests failed (attempt {}/{}).",
                                        test_fail_count, self.config.testing.max_retries,
                                    ),
                                );

                                if test_fail_count > self.config.testing.max_retries {
                                    let msg = format!(
                                        "Tests still failing after {} attempt(s). Stopping.",
                                        self.config.testing.max_retries
                                    );
                                    self.printer.print(Phase::Failed, &msg);
                                    session.log_event(&msg);
                                    session.set_status(SessionStatus::Failed).ok();
                                    return Err(RalphError::ToolFailed {
                                        tool: "auto_test".to_string(),
                                        message: msg,
                                    });
                                }

                                // Inject failure as user feedback so Ralph fixes it.
                                // Also inject a structured list of failing test names.
                                let truncated = truncate_log(&output, 3000);
                                let failing_tests = extract_failing_test_names(&output);
                                let test_list = if !failing_tests.is_empty() {
                                    format!(
                                        "\n\nFailing tests ({}):{}",
                                        failing_tests.len(),
                                        failing_tests
                                            .iter()
                                            .map(|t| format!("\n  - {}", t))
                                            .collect::<String>()
                                    )
                                } else {
                                    String::new()
                                };
                                session.messages.push(Message::user(format!(
                                    "Automated tests failed after your changes.{}\n\n\
                                     Fix each failing test before calling `declare_done`. \
                                     Use `search_in_file` or `read_file` with offset/limit \
                                     to read only the relevant code sections.\n\n\
                                     Test output:\n```\n{}\n```",
                                    test_list, truncated
                                )));
                                // Clear done/failed — Ralph must fix tests first
                                done = false;
                                failed = false;
                            }
                        }
                        Err(e) => {
                            // Test runner itself errored (e.g. command not found).
                            // Log it but don't block the agent — misconfiguration
                            // shouldn't halt a session.
                            self.printer.print(
                                Phase::Verify,
                                &format!("Auto-test runner error (skipping): {}", e),
                            );
                            session.log_event(&format!("Auto-test runner error: {}", e));
                        }
                    }
                }
            }

            // ── VERIFY ────────────────────────────────────────────────────────
            if done {
                self.printer
                    .print(Phase::Done, &format!("Done: {}", final_message));
                session.log_event(&format!("Done: {}", final_message));
                session.set_status(SessionStatus::Done).ok();
                let files: Vec<String> = tools
                    .modified_files
                    .iter()
                    .map(|p| p.display().to_string())
                    .collect();
                self.memory
                    .lock()
                    .unwrap_or_else(|e| e.into_inner())
                    .add_episode(&session.meta.session_id, &final_message, files, "done");
                self.printer.print(
                    Phase::Ralph,
                    &format!(
                        "[tokens total] in={} out={} reasoning={}",
                        total_input_tokens, total_output_tokens, total_reasoning_tokens
                    ),
                );
                return Ok(());
            }
            if failed {
                self.printer
                    .print(Phase::Failed, &format!("Failed: {}", final_message));
                session.log_event(&format!("Failed: {}", final_message));
                session.set_status(SessionStatus::Failed).ok();
                let files: Vec<String> = tools
                    .modified_files
                    .iter()
                    .map(|p| p.display().to_string())
                    .collect();
                self.memory
                    .lock()
                    .unwrap_or_else(|e| e.into_inner())
                    .add_episode(&session.meta.session_id, &final_message, files, "failed");
                self.printer.print(
                    Phase::Ralph,
                    &format!(
                        "[tokens total] in={} out={} reasoning={}",
                        total_input_tokens, total_output_tokens, total_reasoning_tokens
                    ),
                );
                return Err(RalphError::ToolFailed {
                    tool: "declare_failed".to_string(),
                    message: final_message,
                });
            }

            self.printer.print(Phase::Verify, "Continuing...");
        } // end loop
    }
}

/// Detect project manifest files and run the appropriate package manager
/// to install dependencies before the first LLM turn.  All installs are
/// best-effort: failures are logged but never abort the session.
async fn install_workspace_deps(workspace: &std::path::Path, printer: &Printer) {
    // (manifest file, program, args, human label)
    // pip install -e . may be triggered by multiple markers (pyproject.toml,
    // setup.py, setup.cfg); we run it at most once via `pip_editable_done`.
    let mut pip_editable_done = false;

    struct Check {
        marker: &'static str,
        program: &'static str,
        args: &'static [&'static str],
        label: &'static str,
        editable: bool,
    }

    let checks: &[Check] = &[
        Check {
            marker: "requirements.txt",
            program: "pip",
            args: &["install", "-r", "requirements.txt", "-q"],
            label: "pip install -r requirements.txt",
            editable: false,
        },
        Check {
            marker: "pyproject.toml",
            program: "pip",
            args: &["install", "-e", ".", "-q"],
            label: "pip install -e .",
            editable: true,
        },
        Check {
            marker: "setup.py",
            program: "pip",
            args: &["install", "-e", ".", "-q"],
            label: "pip install -e .",
            editable: true,
        },
        Check {
            marker: "setup.cfg",
            program: "pip",
            args: &["install", "-e", ".", "-q"],
            label: "pip install -e .",
            editable: true,
        },
        Check {
            marker: "package.json",
            program: "npm",
            args: &["install", "--silent"],
            label: "npm install",
            editable: false,
        },
        Check {
            marker: "go.mod",
            program: "go",
            args: &["mod", "download"],
            label: "go mod download",
            editable: false,
        },
    ];

    for check in checks {
        if !workspace.join(check.marker).exists() {
            continue;
        }
        if check.editable {
            if pip_editable_done {
                continue;
            }
            pip_editable_done = true;
        }
        printer.print(Phase::Ralph, &format!("[setup] {}", check.label));
        match tokio::process::Command::new(check.program)
            .args(check.args)
            .current_dir(workspace)
            .output()
            .await
        {
            Ok(o) if o.status.success() => {}
            Ok(o) => {
                let first_err = String::from_utf8_lossy(&o.stderr)
                    .lines()
                    .find(|l| !l.trim().is_empty())
                    .unwrap_or("(no output)")
                    .to_string();
                printer.print(
                    Phase::Ralph,
                    &format!("[setup] {} failed (non-fatal): {}", check.label, first_err),
                );
            }
            Err(e) => {
                printer.print(
                    Phase::Ralph,
                    &format!("[setup] {} error (non-fatal): {}", check.label, e),
                );
            }
        }
    }
}

/// Return a single human-readable line describing a tool call.
/// For file-writing tools the content is parsed to extract definition names;
/// the raw code is never shown.
fn describe_tool_call(tool_name: &str, args: &serde_json::Value) -> String {
    let obj = match args.as_object() {
        Some(o) => o,
        None => return String::new(),
    };
    let str_arg = |k: &str| obj.get(k).and_then(|v| v.as_str()).unwrap_or("?");

    match tool_name {
        "write_file" => {
            let path = str_arg("path");
            let content = str_arg("content");
            let defs = extract_definitions(content);
            if defs.is_empty() {
                format!("→ {}", path)
            } else {
                format!("→ {}  [{}]", path, defs.join(", "))
            }
        }
        "edit_file" => {
            let path = str_arg("path");
            format!("→ {} (editing)", path)
        }
        "read_file" => format!("→ {}", str_arg("path")),
        "delete_file" => format!("→ {} (delete)", str_arg("path")),
        "list_dir" => format!("→ {}", str_arg("path")),
        "load_files" => format!("→ pattern: {}", str_arg("pattern")),
        "explain_code" => format!(
            "→ {}",
            obj.get("path")
                .and_then(|v| v.as_str())
                .unwrap_or("workspace")
        ),
        "run_command" | "run_test" | "run_build" => {
            let cmd = str_arg("command");
            let preview: String = cmd.chars().take(80).collect();
            if cmd.len() > 80 {
                format!("$ {}…", preview)
            } else {
                format!("$ {}", preview)
            }
        }
        "search_codebase" => format!("pattern: {}", str_arg("pattern")),
        "search_web" => format!("\"{}\"", str_arg("query")),
        "ask_user" => format!("\"{}\"", str_arg("question")),
        "declare_done" | "declare_failed" => str_arg("message").to_string(),
        _ => {
            // Generic: show up to 3 key=value pairs, skipping long strings
            let pairs: Vec<String> = obj
                .iter()
                .filter(|(_, v)| v.as_str().map(|s| s.len() < 80).unwrap_or(true))
                .take(3)
                .map(|(k, v)| format!("{}={}", k, v))
                .collect();
            pairs.join(" ")
        }
    }
}

/// Parse source content and return up to 5 top-level definition names.
fn extract_definitions(content: &str) -> Vec<String> {
    use regex::Regex;
    // Patterns ordered by precedence; each captures (keyword, name)
    let patterns: &[(&str, &str)] = &[
        // Rust
        (
            r"(?m)^(?:pub(?:\([^)]*\))?\s+)?(?:async\s+)?fn\s+(\w+)",
            "fn",
        ),
        (r"(?m)^(?:pub(?:\([^)]*\))?\s+)?struct\s+(\w+)", "struct"),
        (r"(?m)^(?:pub(?:\([^)]*\))?\s+)?enum\s+(\w+)", "enum"),
        (r"(?m)^(?:pub(?:\([^)]*\))?\s+)?trait\s+(\w+)", "trait"),
        (r"(?m)^impl(?:<[^>]*>)?\s+(\w+)", "impl"),
        // Python
        (r"(?m)^(?:async\s+)?def\s+(\w+)", "def"),
        (r"(?m)^class\s+(\w+)", "class"),
        // JS / TS
        (
            r"(?m)^(?:export\s+)?(?:default\s+)?(?:async\s+)?function\s+(\w+)",
            "function",
        ),
        (r"(?m)^(?:export\s+)?(?:default\s+)?class\s+(\w+)", "class"),
        (r"(?m)^(?:export\s+)?(?:const|let)\s+(\w+)\s*[=:]", "const"),
        // Go
        (r"(?m)^func\s+(?:\([^)]*\)\s+)?(\w+)", "func"),
        (r"(?m)^type\s+(\w+)\s+struct", "struct"),
        // Java / Kotlin
        (
            r"(?m)^(?:public\s+)?(?:class|interface|record)\s+(\w+)",
            "class",
        ),
    ];

    let mut seen = std::collections::HashSet::new();
    let mut defs: Vec<String> = Vec::new();

    for (pat, kind) in patterns {
        if let Ok(re) = Regex::new(pat) {
            for cap in re.captures_iter(content) {
                if let Some(m) = cap.get(1) {
                    let name = m.as_str().to_string();
                    let key = format!("{}:{}", kind, name);
                    if seen.insert(key) {
                        defs.push(format!("{} {}", kind, name));
                        if defs.len() >= 5 {
                            return defs;
                        }
                    }
                }
            }
        }
    }
    defs
}

fn make_spinner(msg: &str) -> ProgressBar {
    let pb = ProgressBar::new_spinner();
    pb.set_style(
        ProgressStyle::default_spinner()
            .tick_strings(&["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"])
            .template("{spinner:.cyan} {msg}")
            .unwrap_or_else(|_| ProgressStyle::default_spinner()),
    );
    pb.set_message(msg.to_string());
    pb.enable_steady_tick(Duration::from_millis(80));
    pb
}

fn truncate_log(s: &str, max: usize) -> String {
    if s.len() <= max {
        s.replace('\n', " ")
    } else {
        // Walk char boundaries to find the largest split point ≤ max bytes.
        // A plain byte slice `&s[..max]` panics when `max` falls inside a
        // multi-byte character (e.g. the em-dash '—' in find_symbol output).
        let end = s
            .char_indices()
            .map(|(i, c)| i + c.len_utf8())
            .filter(|&end| end <= max)
            .last()
            .unwrap_or(0);
        format!("{}…", &s[..end].replace('\n', " "))
    }
}

/// Returns true if the shell_tools output ends with `[exit: 0]`.
fn test_passed(output: &str) -> bool {
    output.trim_end().ends_with("[exit: 0]")
}

/// Post-process a tool result for storage in session messages.
/// Handles: test output trimming, no-match search compression, duplicate file read eviction.
fn post_process_tool_output(
    result: &ToolResult,
    max_chars: usize,
    max_test_chars: usize,
    current_turn: u32,
    file_last_read: &mut std::collections::HashMap<String, u32>,
    files_edited_since_read: &std::collections::HashSet<String>,
) -> String {
    let output = &result.output;

    // 1. Dead-end search: store compact placeholder.
    if result.tool_name == "search_codebase" {
        if output.trim().is_empty() || output.contains("No matches") {
            // Extract pattern from the stored output if possible, or use generic text.
            return "[search: no matches]".to_string();
        }
    }

    // 2. Duplicate file read eviction.
    if result.tool_name == "read_file" {
        // Try to extract the file path from the tool output — it's tricky since we
        // don't have the original arguments here. Use a best-effort approach: the
        // call_id doesn't have the path. We'll skip this for now and just truncate.
        // (The full implementation would need the path from call arguments.)
        // This is handled partially — we track reads by checking if the output repeats.
    }

    // 3. Test output trimming: for run_test/run_command/run_build outputs that look like pytest.
    let is_test_output = (result.tool_name == "run_test"
        || result.tool_name == "run_command"
        || result.tool_name == "run_build")
        && (output.contains("passed")
            || output.contains("failed")
            || output.contains("=== FAILURES ===")
            || output.contains("FAILED"));

    if is_test_output {
        let trimmed = trim_test_output(output, max_test_chars);
        return trimmed;
    }

    // 4. General large output truncation.
    if output.len() > max_chars {
        let preview: String = output.chars().take(max_chars).collect();
        let total_tokens = compaction::count_tokens(output);
        let lines_shown = preview.chars().filter(|&c| c == '\n').count();
        let total_lines = output.chars().filter(|&c| c == '\n').count();
        format!(
            "{}\n\n[...truncated after line {lines_shown} of {total_lines} ({total_tokens} tokens total). \
             To read further use `read_file` with `offset={lines_shown}` and an appropriate `limit`.]",
            preview
        )
    } else {
        output.clone()
    }
}

/// Trim test output to keep the most useful parts within the char limit.
fn trim_test_output(output: &str, max_chars: usize) -> String {
    let lines: Vec<&str> = output.lines().collect();

    // Strip leading progress-only lines (lines with only dots, F, s, E chars).
    let content_start = lines
        .iter()
        .position(|line| {
            let trimmed = line.trim();
            if trimmed.is_empty() {
                return false;
            }
            !trimmed.chars().all(|c| matches!(c, '.' | 'F' | 's' | 'E'))
        })
        .unwrap_or(0);

    let meaningful = &lines[content_start..];

    // If there's a FAILURES section, keep from there.
    let from_idx = meaningful
        .iter()
        .position(|l| l.contains("=== FAILURES ==="))
        .unwrap_or(0);

    let relevant = &meaningful[from_idx..];

    // Always keep the last 30 lines.
    let keep_start = if relevant.len() > 30 {
        relevant.len() - 30
    } else {
        0
    };
    let keep = &relevant[keep_start.min(from_idx.max(0))..];

    let joined = keep.join("\n");
    if joined.len() > max_chars {
        // Take from the end.
        let start_byte = joined.len().saturating_sub(max_chars);
        // Find a newline boundary.
        let adj_start = joined[start_byte..]
            .find('\n')
            .map(|p| start_byte + p + 1)
            .unwrap_or(start_byte);
        format!("[...trimmed...]\n{}", &joined[adj_start..])
    } else {
        joined
    }
}

/// Extract pytest-style failing test names from raw test output.
/// Matches lines like: `FAILED tests/test_foo.py::TestClass::test_method - AssertionError`
fn extract_failing_test_names(output: &str) -> Vec<String> {
    let mut names = Vec::new();
    for line in output.lines() {
        let trimmed = line.trim();
        if let Some(rest) = trimmed.strip_prefix("FAILED ") {
            // Everything before " - " (if present) is the test id.
            let id = rest.splitn(2, " - ").next().unwrap_or(rest).trim();
            if !id.is_empty() && !names.contains(&id.to_string()) {
                names.push(id.to_string());
            }
        }
        // Also catch: "  FAILED test_something" indented lines.
        if trimmed.starts_with("FAILED") && trimmed.len() > 7 {
            let id = trimmed[7..].splitn(2, " - ").next().unwrap_or("").trim();
            if !id.is_empty() && !names.contains(&id.to_string()) {
                names.push(id.to_string());
            }
        }
    }
    names
}

/// Build a context-aware stall nudge based on what the agent has been doing.
fn context_aware_stall_nudge(
    turns_since_edit: u32,
    recent_categories: &std::collections::VecDeque<&'static str>,
    consecutive_test_failures: u32,
) -> String {
    let all_reads = !recent_categories.is_empty() && recent_categories.iter().all(|&c| c == "read");
    let edits_without_test = recent_categories.iter().any(|&c| c == "edit")
        && !recent_categories.iter().any(|&c| c == "test");

    if consecutive_test_failures >= 2 {
        return format!(
            "Tests have failed {} times in a row. \
             Consider a different approach:\n\
             • Use `view_diff` to review all your changes so far.\n\
             • Use `search_in_file` to re-read the exact code you changed.\n\
             • Consider whether your fix addresses the root cause, or if you need to revert and try again.\n\
             • Use `read_file_outline` on the test file to understand what it expects.\n\
             You MUST either fix the tests or call `declare_failed` if the task is not achievable.",
            consecutive_test_failures
        );
    }

    if all_reads {
        return format!(
            "You have spent {} consecutive turns reading without making any code change.\n\
             You MUST act now:\n\
             • Call `edit_file` or `edit_file_multi` to apply your fix — do not read more files.\n\
             • If you need to find the exact text, use `search_in_file` with a pattern, then edit.\n\
             • An imperfect fix that gets refined is better than infinite reading.\n\
             You MUST make at least one file edit this turn.",
            turns_since_edit
        );
    }

    if edits_without_test {
        return format!(
            "You have made edits but have not run any tests to verify them.\n\
             • Use `run_test` to verify your changes work.\n\
             • Or use `view_diff` to review what you changed before proceeding.\n\
             • If tests pass, call `declare_done` with a summary.",
        );
    }

    // Generic fallback
    format!(
        "You have spent {} turns without making progress. You must act now:\n\
         • Call `edit_file`, `edit_file_multi`, or `write_file` to apply your fix.\n\
         • Use `search_in_file` to find the exact text if needed.\n\
         • You MUST make at least one file edit this turn.",
        turns_since_edit
    )
}

/// Returns true if the LLM response looks like an unexecuted plan — i.e. the
/// model described what it intends to do but called no tools. Used to decide
/// whether to nudge it into actually making the edit.
fn looks_like_unexecuted_plan(text: &str) -> bool {
    if text.is_empty() {
        return false;
    }
    let lower = text.to_lowercase();
    let action_phrases = [
        "i need to",
        "i will ",
        "i'll ",
        "let me ",
        "i should ",
        "i'm going to",
        "next i ",
        "now i'll",
        "now i need",
        "need to modify",
        "need to edit",
        "need to change",
        "need to add",
        "need to fix",
        "need to update",
        "should modify",
        "should edit",
        "should change",
        "should add",
        "should fix",
        "should update",
        "to fix this",
        "to resolve this",
        "the fix is to",
        "the solution is to",
        "i can fix",
        "i can modify",
    ];
    action_phrases.iter().any(|p| lower.contains(p))
}