agent-kernel 0.1.0

use crate::{Agent, BoxFuture};

/// Context provided to an evolution operation.
///
/// Passed to [`EvolutionRuntime::evolve`] to give the LLM enough information
/// to produce an improved SOUL.md.
pub struct EvolutionContext {
    /// Key insights accumulated from past discussions.
    pub memories: Vec<String>,
    /// Human-readable summary of recent feedback (e.g. "3 ratings averaging 4.2 stars").
    pub feedback_summary: String,
    /// Current weighted-average quality score (0.0–5.0).
    pub current_quality_score: f64,
}

/// Persistent self-evolution primitives (Sixth Principle: persistent self-evolution).
///
/// This trait is the Phase 2 addition in the independent agent-kernel repository.
/// Implement this trait in the product shell (e.g. OhMyZeroClaw) to wire up
/// feedback tracking, memory storage, SOUL.md optimization, and version rollback.
///
/// Only the trait definition lives in the kernel — no implementation provided.
pub trait EvolutionRuntime: Send + Sync {
    /// Record user feedback for an agent and return the updated quality_score.
    fn feedback<'a>(
        &'a self,
        agent: &'a str,
        rating: u8,
        comment: Option<&'a str>,
    ) -> BoxFuture<'a, anyhow::Result<f64>>;

    /// Store a discussion insight into the agent's persistent memory.
    fn remember<'a>(
        &'a self,
        agent: &'a str,
        insight: &'a str,
        tags: &'a [String],
    ) -> BoxFuture<'a, anyhow::Result<()>>;

    /// Evolve an agent's SOUL.md given an EvolutionContext. Returns the new SOUL.md.
    fn evolve<'a>(
        &'a self,
        agent: &'a Agent,
        context: &'a EvolutionContext,
    ) -> BoxFuture<'a, anyhow::Result<String>>;

    /// Roll back an agent's SOUL.md to a specific version. Returns the rolled-back SOUL.md.
    fn rollback<'a>(
        &'a self,
        agent: &'a str,
        version: u32,
    ) -> BoxFuture<'a, anyhow::Result<String>>;
}