//! Mandatory explore phase — spawns parallel subagents to discover context
//! before the main agent begins its turn.
//!
//! # Flow
//!
//! Before the main agent's LLM loop, [`ExploreService::explore`] dispatches
//! at least 3 subagents in parallel (code-structure scan, symbol-index query,
//! semantic-context search). Their findings are consolidated into a single
//! system message that is prepended to the conversation.
//!
//! # Why mandatory
//!
//! Without structured exploration the main agent works from an empty context
//! window. The explore phase guarantees that every turn starts with a compact
//! snapshot of what the codebase contains and where relevant code lives.

use anyhow::Result;
use std::collections::VecDeque;
use std::future::Future;
use std::pin::Pin;
use std::sync::{Arc, Mutex};
use zesdex_domain::agent::TurnEvent;

/// The consolidated output of an explore phase — a set of system-level
/// context messages injected before the main agent prompt.
#[derive(Debug, Clone)]
pub struct ExploreOutput {
    /// One or more system messages summarising what the explore subagents
    /// discovered. Prepended to the conversation by the turn service.
    pub context_messages: Vec<String>,
    /// Short human-readable summary of what was explored.
    pub summary: String,
}

/// Service trait for the mandatory pre-turn exploration phase.
///
/// Implementors spawn ≥3 parallel subagents, each analysing a different
/// aspect of the workspace, and return a consolidated summary.
///
/// # Object safety
///
/// This trait is `dyn`-safe — it returns `Pin<Box<dyn Future>>` so it can
/// be stored as `Arc<dyn ExploreService>`.
pub trait ExploreService: Send + Sync {
    /// Run the explore phase.
    ///
    /// `query` — the user's current input phrase.
    /// `workspace_root` — absolute path to the workspace root.
    /// `turn_events` — shared event queue for TUI updates.
    /// Returns structured context messages and a summary blob.
    fn explore<'a>(
        &'a self,
        query: &'a str,
        workspace_root: &'a str,
        turn_events: &'a Arc<Mutex<VecDeque<TurnEvent>>>,
    ) -> Pin<Box<dyn Future<Output = Result<ExploreOutput>> + Send + 'a>>;
}