let orchestrator = Orchestrator::new(runner, registry) // Arc<dyn AgentRlRunner>, Arc<ToolRegistry>
    .with_memory(memory)         // Arc<dyn Memory>: record solved problems for recall
    .with_config(config)         // OrchestratorConfig
    .with_id_fn(Arc::new(|| ...)); // deterministic tool ids (tests)

let outcome: SolveOutcome = orchestrator.solve("the task").await?;

pub struct OrchestratorConfig {
    pub max_rl_rounds: u32,     // bound on plan→propose→retry (default 1)
    pub num_proposals: usize,   // proposals per round (default 2)
    pub registry_search_k: usize, // tools to pre-load before the general run (default 5)
    pub session_id: String,     // memory session (default "agentrl")
}

pub struct SolveOutcome {
    pub solved: bool,
    pub how: Option<Solved>,
    pub last_graph: ExecutionGraph,
    pub answer: String,
}

pub enum Solved {
    Directly,              // GeneralAgent solved it on the first pass
    ByCachedTool(String),  // solved via a previously-registered tool (cache hit)
    ByNewTool(String),     // RL loop fired: a proposal won and was registered
}

#[async_trait]
pub trait AgentRlRunner: Send + Sync {
    async fn run_general(&self, task: &str, available: &[RegistryEntry]) -> GeneralResult;
    async fn plan(&self, trace: &FailureTrace, n: usize) -> Vec<Proposal>;
    async fn run_proposal(&self, proposal: &Proposal) -> ProposalOutcome;
    async fn promote(&self, _winner: &ProposalOutcome) {} // default: no-op
}

let runner = CerseiRunner::new(
        provider_factory,  // ProviderFactory = Arc<dyn Fn() -> Box<dyn Provider> + Send + Sync>
        "./work",          // working directory
        registry,          // Arc<ToolRegistry>
        verifier,          // Arc<dyn Verifier>
    )
    .with_model("gemini-3.1-pro-preview")
    .with_max_turns(16)
    .with_general_max_turns(4)   // optional: cheaper first pass
    .with_general_tools(factory); // optional: restrict the GeneralAgent's toolset

let gr = GraphReporter::new();
let agent = Agent::builder()./* ... */.reporter(gr.clone()).build()?;
agent.run(task).await?;
let graph: ExecutionGraph = gr.graph();           // snapshot
let trace: FailureTrace = graph.failure_trace(task); // distilled directionality

let registry = ToolRegistry::open("~/.cersei/agentrl")?; // jsonl-backed, loads on open
// or: let registry = ToolRegistry::in_memory();          // for tests

registry.register(entry)?;                 // scrubs + appends to entries.jsonl
let hits = registry.search("build a parser", 5); // keyword ranking (MVP)
let one = registry.get(&tool_id);
let all = registry.all();
registry.record_success(&tool_id);         // bump a tool's success counter

// `replayer` knows how to re-apply a SolutionSpec (CerseiRunner provides one
// that spawns a fresh sub-agent seeded from the spec).
let tool = DynamicTool::new(entry, replayer); // impl Tool { name, description, execute }

#[async_trait]
pub trait SolutionReplayer: Send + Sync {
    async fn replay(&self, entry: &RegistryEntry, goal: &str, ctx: &ToolContext) -> ToolResult;
}

#[async_trait]
pub trait Verifier: Send + Sync {
    async fn verify(&self, workdir: &Path) -> VerifyResult; // { passed: bool, detail: String }
}

// Built-in: runs a shell command in the working dir; passes iff exit 0.
let v = CommandVerifier::new("cargo test"); // default 120s timeout

cersei_agentrl::memory_bridge::record_solution(
    &memory, session_id, problem, tool_name, tool_id,
).await?;