//! AgentRunner trait — the caller's model loop abstraction.
//!
//! Since the runtime doesn't own the model, the caller implements this trait
//! to drive the model loop (call LLM, parse response, submit proposals, repeat).
//! car-multi orchestrates *when* and *how* agents run, but the caller decides
//! *what* each agent does.

use crate::error::MultiError;
use crate::mailbox::Mailbox;
use crate::types::{AgentOutput, AgentSpec};
use car_engine::Runtime;

/// Trait for running an agent to completion.
///
/// Implement this with your model loop. For example:
/// 1. Initialize chat with `spec.system_prompt`
/// 2. Send `task` to the model
/// 3. Parse response into `ActionProposal`
/// 4. Call `runtime.execute(&proposal)`
/// 5. Format results back to model
/// 6. Repeat until model says "done"
/// 7. Return `AgentOutput`
#[async_trait::async_trait]
pub trait AgentRunner: Send + Sync {
    async fn run(
        &self,
        spec: &AgentSpec,
        task: &str,
        runtime: &Runtime,
        mailbox: &Mailbox,
    ) -> Result<AgentOutput, MultiError>;
}
