lernie 0.0.2

//! Root-conversation branch orchestration (ARCH §2.3–§2.10).
//!
//! [`run_exchange`] executes a single root conversation: spawn branch
//! `agents/<conv-id>` off the default config head (§2.2–§2.3); write the
//! step-1 dispatch commit (§2.2, §2.10); then the step loop (§2.5) —
//! drain the inbox ([`drain`], §2.11), interpret delivered child results
//! and the compaction checkpoint at each boundary (the §6 prompt→advance
//! collapse, [`child_result`]), drive the model call through the retry
//! loop ([`model_call`], §4.4), re-assemble history from the read-state
//! commit ([`assembler`], §2.3, §5), and loop on a settled `tool_use`.
//! Every terminal deposits a result message ([`result_deposit`], §2.6,
//! no-op for a root), then runs the shared §2.11 terminal tail
//! (`terminal::conclude`): terminal-lifecycle bindings (§6), lease
//! release through the §2.11 release rule (a deposit that raced the last
//! drain is launched for, [`driver`]), and the epitaph-valued exit
//! launches at own agent and at the parent the deposit revived.

pub mod advance;
mod assembler;
mod child_result;
mod drain;
pub mod driver;
mod model_call;
mod result_deposit;
mod staging;
mod step_commit;
pub mod stop_signal;
mod terminal;
mod tool_step;
mod tools;
mod transcript;
mod transfer;

pub use model_call::{RealSleeper, Sleeper};
pub(crate) use step_commit::remove_control_files;
pub use stop_signal::{flag as stop_flag, install as install_stop_handler};

use super::inbox::{self, Epitaph};
use super::step::{RESPONSE_FILE, STAGING_FILE, StepMeta, step_dir_rel};
use super::{Deps, Error};
use crate::config::manifest::RoleRules;
use crate::config::{Budgets, Model, RetryConfig, Workflow};
use assembler::assemble;
use brazen::Content;
use model_call::ModelCall;
use std::ffi::OsString;
use std::path::Path;
use step_commit::{
    commit_dispatch, prepend_goal, read_branch_tip, spawn_branch, write_dispatch_files, write_meta,
    write_request,
};
use tool_step::run_tool_calls;

/// Per-request `max_tokens` output cap — one model call's output ceiling,
/// distinct from the §6 spend budgets ([`Budgets`]) and from the §5.2
/// manifest's `budget_tokens` (an assembled-context budget, no output cap).
const DEFAULT_MAX_TOKENS: u32 = 4096;

/// Inputs resolved by [`super::run`] before branch work starts.
pub(super) struct Resolved<'a> {
    /// The agent's role (§4.3) — governs what the request declares
    /// ([`tools::compose`]) and what it may call ([`tool_step`]).
    pub(super) role: &'a str,
    pub(super) model: &'a Model,
    /// brazen provider-row name passed as `bz --provider <row>` (§4.4).
    pub(super) provider_row: &'a str,
    /// The role's declared tool names (§4.3 `tools:`), composed by [`tools`].
    pub(super) tools: &'a [String],
    pub(super) soul: String,
    /// The adapter binary (`bz` or the `adapter:` override, §4.2).
    pub(super) binary: OsString,
    /// Harness-owned retry policy from `workflow.yaml` (§2.10, §6).
    pub(super) retry: RetryConfig,
    /// Per-conversation spend limits from `workflow.yaml` (§6), checked
    /// at every model-call boundary.
    pub(super) budgets: Budgets,
    /// The full workflow (§6): per-step hooks and lifecycle bindings, the
    /// same seams `lernie advance` runs (the §6 prompt→advance collapse).
    pub(super) workflow: &'a Workflow,
    /// The role's §5.2 context-assembly rules (`manifest.yaml`, §2.2);
    /// `None` (no entry for the role) assembles the transcript alone.
    pub(super) manifest: Option<&'a RoleRules>,
    /// True under an `adapter:` override — the MessageStart.v handshake
    /// governs in place of the version guard (§4.4).
    pub(super) expect_handshake: bool,
}

/// Drive one root conversation against an already-resolved config.
/// Returns the branch name so the caller can surface it on stdout.
pub(super) fn run_exchange(
    repo: &Path,
    user_message: &str,
    resolved: &Resolved<'_>,
    deps: &Deps<'_>,
) -> Result<String, Error> {
    let ts = deps.clock.now_compact();
    let short_id = deps.id_gen.short();
    let conv_id = format!("{ts}-{short_id}");
    let branch_name = conv_id.clone();
    let worktree_path = crate::workspace::agent_worktree(repo, &conv_id);

    // Executor lock (§2.11): acquire the branch's inbox lease before any
    // work, held for the whole loop and kernel-released on exit. Losing
    // the acquire means another driver owns this branch — clean no-op
    // (Writer/driver totality); a fresh root always wins (unique conv-id).
    let inbox = inbox::inbox_dir(repo, &conv_id);
    let executor_lock = match inbox::try_acquire(&inbox).map_err(|source| Error::ExecutorLock {
        path: inbox.clone(),
        source,
    })? {
        Some(guard) => guard,
        None => return Ok(branch_name),
    };

    spawn_branch(repo, &worktree_path, &conv_id, deps)?;

    // The initial user message enters through the front door (§2.4,
    // §2.11): deposited into this agent's own inbox, delivered by the
    // step-1 drain — the same path any reprompt takes.
    inbox::deposit(repo, &conv_id, inbox::USER_SENDER, user_message, deps.clock)?;

    let system_with_goal = prepend_goal(user_message, &resolved.soul);

    let call = ModelCall {
        adapter: deps.adapter,
        sleeper: deps.sleeper,
        binary: &resolved.binary,
        provider_row: resolved.provider_row,
        retry: resolved.retry,
        stop: deps.stop,
        expect_handshake: resolved.expect_handshake,
    };

    let mut step_seq: u32 = 1;
    let mut exhausted = false;
    // §2.9 step 3: set when a check point sees the SIGTERM handler flag.
    let mut stopped = false;
    // What the latest drain deliberately left pending — the §2.11
    // release rule's diff base at the tail (every loop exit follows an
    // assignment, so this is never unset).
    let mut seen;
    loop {
        if step_seq == 1 {
            write_dispatch_files(&worktree_path, user_message, &resolved.soul)?;
            commit_dispatch(&worktree_path, &conv_id, deps)?;
        }

        // Step-boundary drain (§2.11 *Delivery*): move each pending inbox
        // message into the transcript ahead of this step's read-state
        // capture — after the prior step's tool entries, so a message
        // never wedges between paired tool blocks (§2.3).
        seen = drain::drain(&worktree_path, &inbox, &conv_id, deps.git)?.left;

        // §6 prompt→advance collapse: interpret delivered child results
        // (deliver_result / compaction_merge / verifier gate) at the same
        // boundary `lernie advance` does — empty-inputs no-op for a root.
        child_result::interpret_pending(repo, &conv_id, &worktree_path, resolved.workflow, deps)?;

        let commit_sha = read_branch_tip(&worktree_path, deps)?;

        // §2.9 step 3 check point: a stop between steps (or during a prior
        // step's tool work) is caught here, before the next model call.
        if stop_signal::stopped(deps.stop) {
            stopped = true;
            break;
        }

        // §6 budget check (deposits + marks the ref on exhaustion, §2.9).
        if terminal::budget_exhausted(
            repo,
            &conv_id,
            &branch_name,
            &worktree_path,
            &resolved.budgets,
            deps,
        )? {
            exhausted = true;
            break;
        }

        // §2.3 / §5: assemble the model-facing history from the read-state
        // commit's tree — §5.2 head/body under the role's manifest rules,
        // then the transcript tail — one path for running, retry, replay.
        let messages = assemble(&worktree_path, resolved.manifest)?;
        let tools = tools::compose(&worktree_path, resolved.role, resolved.tools, &messages)?;
        let request = model_call::build_request(
            &resolved.model.model_id,
            &system_with_goal,
            messages,
            tools,
            DEFAULT_MAX_TOKENS,
        );
        let request_value =
            serde_json::to_value(&request).expect("CanonicalRequest is always serializable");
        let step_dir_rel_str = step_dir_rel(&conv_id, step_seq);
        write_request(repo, &step_dir_rel_str, &request_value)?;

        let request_bytes =
            serde_json::to_vec(&request).expect("CanonicalRequest is always serializable");
        let started_at = deps.clock.now_iso8601();
        let response_path = repo.join(&step_dir_rel_str).join(RESPONSE_FILE);
        let call_outcome = model_call::run(&call, &request_bytes, &response_path);
        // §2.9 step 3 check point: a stop during the call killed `bz`. The
        // flag classifies, not the error's shape ([`model_call`]) — swallow
        // whatever it surfaced (on-disk signature untouched) and exit.
        if stop_signal::stopped(deps.stop) {
            stopped = true;
            break;
        }
        call_outcome?;
        let ended_at = deps.clock.now_iso8601();

        write_meta(
            repo,
            &step_dir_rel_str,
            &StepMeta {
                commit: commit_sha,
                started_at,
                ended_at,
            },
        )?;

        // Transcript writer (§2.3): seal-and-rename the staging entry to
        // `messages/NNN-<model-id>.json` (origin = authoring model) + commit.
        let staging_path = repo.join(&step_dir_rel_str).join(STAGING_FILE);
        let assistant_content = transcript::commit_assistant(
            &worktree_path,
            &conv_id,
            &resolved.model.model_id,
            &staging_path,
            deps.git,
        )?;

        // No `tool_use` block is terminal (§2.5): deposit a `final-response`
        // result, response body iff the agent spoke (§2.6). No-op for a root.
        if !assistant_content
            .iter()
            .any(|b| matches!(b, Content::ToolUse { .. }))
        {
            let response = result_deposit::terminal_text(&assistant_content);
            result_deposit::deposit_terminal(
                repo,
                &conv_id,
                &worktree_path,
                Epitaph::FinalResponse,
                response.as_deref(),
                deps,
            )?;
            break;
        }

        // §2.5 pairing: run each tool_use, committing its tool_result as a
        // transcript entry (§2.3); the next step re-assembles from the tree.
        // §2.9 step 3 check point: a stop landing in this tool-execution
        // window (the group SIGTERM felled the running tool) breaks here for
        // the same stopped-deposit exit as the model-call window.
        if run_tool_calls(
            repo,
            &worktree_path,
            &conv_id,
            resolved.role,
            &step_dir_rel_str,
            &assistant_content,
            deps,
        )? {
            stopped = true;
            break;
        }

        // §6 collapse: the `compaction:` checkpoint clock, same seam as
        // `lernie advance` (`worker_flush` → dispatch a compactor off C).
        child_result::run_flush(repo, &conv_id, &worktree_path, resolved.workflow, deps)?;
        step_seq += 1;
    }

    // The shared §2.11 terminal tail ([`terminal::conclude`] — the same
    // sequence as the `lernie advance` hop's): finish by epitaph value
    // (a stopped branch deposits its result on the way out; a final
    // response deposited in the loop; an exhausted branch at the boundary
    // check), terminal-lifecycle bindings (§6), release through the
    // release rule (a deposit that raced this loop's last drain launches
    // whatever the epitaph), then the epitaph-valued exit launches. No
    // terminal compaction (§2.7 — the stage is deleted).
    let epitaph = match (stopped, exhausted) {
        (true, _) => Epitaph::Stopped,
        (false, true) => Epitaph::BudgetExhausted,
        (false, false) => Epitaph::FinalResponse,
    };
    terminal::conclude(
        repo,
        &conv_id,
        epitaph,
        resolved.workflow,
        executor_lock,
        &seen,
        deps,
    )?;

    Ok(branch_name)
}