lernie 0.0.2

A git-backed agent harness
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202

//! `lernie advance <workspace> <agent>` — the §6 driver verb: one hop
//! of the workflow chain.
//!
//! Every §2.11 launch seam spawns this verb (detached, via the injected
//! launcher), the exec baton hands one hop to the next (§6), and an
//! operator runs the same verb by hand — launch after a crash, launch
//! after a deposit, and hand-run are indistinguishable, which is the
//! §6 collapse of "advance" and "resume". A hop:
//!
//! 1. **takes the lease** — an adopted predecessor fd or a fresh
//!    acquire ([`crate::prompt::inbox::baton`]); losing the acquire is
//!    the clean no-op of Writer/driver totality (§2.11).
//! 2. **delivers** — [`super::driver::deliver`]: rematerialize, stray
//!    recovery, delivery commits (§2.11).
//! 3. **derives warrant from the tree** ([`warrant`]) — no launcher
//!    decides warrant; the driver decides under the lock (§2.11). The
//!    derivation is the wire alternation itself (§2.3): a transcript
//!    tail ending user-side means a model call is due.
//! 4. **runs one step** ([`hop`]) — the same step machinery
//!    [`super::run_exchange`] drives.
//! 5. **hands off** — tools ran → [`AdvanceOutcome::ToolsPending`]
//!    carries the live lease out for the caller to exec the successor
//!    (§6 exec baton, [`cli`]); a terminal event ends the chain through
//!    the §2.11 exit protocol (deposit at the terminal event → release →
//!    epitaph-valued launches, at own agent and at the parent the
//!    deposit revived → return).
//!
//! Config resolution is **lazy** (the `resolve` closure): a no-op hop
//! exits before any config file is read or any `bz --version` guard
//! runs, so the pin-1 recursion terminator costs nothing but the probe.

pub mod cli;
mod hop;

#[cfg(test)]
mod tests;

use super::{assembler, child_result, driver, terminal};
use crate::prompt::inbox::{self, ExecutorLock};
use crate::prompt::resolve::WorkerConfig;
use crate::prompt::{Deps, Error};
use brazen::{Content, Message, Role};
use std::path::Path;

/// What one hop found and did — derived on the fly, nothing stored.
#[derive(Debug)]
pub enum AdvanceOutcome {
    /// Another executor holds the lock: the branch is already driven —
    /// the clean no-op of Writer/driver totality (§2.11).
    AlreadyDriven,
    /// Nothing is due: empty inbox and a transcript tail with no model
    /// call pending — the §2.11 pin-1 silent exit, terminating the
    /// exit-launch recursion. The exit honours the §2.11 release rule
    /// ([`driver::release_then_reprobe`]): a deposit that raced this
    /// hop's last inbox read is launched for after the release, so
    /// "silent" never means "stranding".
    NothingToDo,
    /// The hop stepped to a terminal event and ran the §2.11 exit
    /// protocol; the chain ends here. The epitaph is not carried — the
    /// exit protocol already wrote it to disk (the deposited result
    /// message, §2.11), its single authoritative home (PRINCIPLES SSOT).
    Terminal,
    /// The step emitted `tool_use` and its tools ran: the successor hop
    /// must run. Carries the live lease for the §6 exec baton — the
    /// caller preps the successor command ([`cli`], `baton`) and execs.
    ToolsPending(ExecutorLock),
}

/// What the transcript tail warrants (§6 hop step 3).
#[derive(Debug, PartialEq, Eq)]
enum Warrant {
    /// Tail ends user-side (delivered mail, committed tool results): a
    /// model call is due.
    ModelCallDue,
    /// Tail ends assistant-side without `tool_use`, or is empty: nothing
    /// is due (§2.11 pin 1).
    NothingDue,
    /// Tail ends assistant-side with `tool_use` unmatched by committed
    /// tool results: the one non-replayable state (§6), declined loudly.
    Unpaired,
}

/// Derive warrant from the assembled wire history (§6): the alternation
/// grouping (§2.3) makes the tail's role the whole answer — committed
/// tool results compose tool-side (canonical `Role::Tool`, §2.3) and
/// delivered mail user-side, so either non-assistant tail is the same
/// observation: a model call is due.
fn warrant(messages: &[Message]) -> Warrant {
    match messages.last() {
        None => Warrant::NothingDue,
        Some(m) if matches!(m.role, Role::User | Role::Tool) => Warrant::ModelCallDue,
        Some(m)
            if m.content
                .iter()
                .any(|b| matches!(b, Content::ToolUse { .. })) =>
        {
            Warrant::Unpaired
        }
        Some(_) => Warrant::NothingDue,
    }
}

/// Run one hop against `agent_id`'s branch. `lease` is a lease the
/// caller already took (the adopted §6 baton fd); `None` acquires here
/// — losing the acquire is [`AdvanceOutcome::AlreadyDriven`]. `resolve`
/// loads the role config lazily, only once a step is warranted (`&mut
/// dyn` rather than `impl FnOnce` so the function has one instantiation
/// and one coverage record).
pub(in crate::prompt) fn run(
    workspace: &Path,
    agent_id: &str,
    lease: Option<ExecutorLock>,
    deps: &Deps<'_>,
    resolve: &mut dyn FnMut() -> Result<WorkerConfig, Error>,
) -> Result<AdvanceOutcome, Error> {
    let lock = match lease {
        Some(lock) => lock,
        None => {
            let inbox_dir = inbox::inbox_dir(workspace, agent_id);
            match inbox::try_acquire(&inbox_dir).map_err(|source| Error::ExecutorLock {
                path: inbox_dir.clone(),
                source,
            })? {
                Some(lock) => lock,
                None => return Ok(AdvanceOutcome::AlreadyDriven),
            }
        }
    };

    // `delivery.left` is what this executor's last inbox read under the
    // lease deliberately left pending — the §2.11 release rule's diff
    // base for every voluntary release below (the two no-op exits and
    // the terminal arm alike).
    let delivery = driver::deliver(workspace, agent_id, deps.git)?;
    let seen = delivery.left;
    let worktree = crate::workspace::agent_worktree(workspace, agent_id);
    if !worktree.exists() {
        // Torn down and no mail: quiescent, nothing due (§2.3 step 6).
        driver::release_then_reprobe(lock, workspace, agent_id, &seen, deps.launcher);
        return Ok(AdvanceOutcome::NothingToDo);
    }

    // §6 delivered-child-result circumstance: interpret any result message
    // the drain left in the inbox (deliver_result / compaction_merge / a
    // gate-hold, keyed on the returning child's role). This needs the
    // workflow, so resolve once when a result is pending — a no-op hop has
    // none and still resolves nothing (lazy resolution). The resolved
    // config is reused by the step below rather than read twice.
    let mut cfg = None;
    if child_result::has_pending_result(workspace, agent_id)? {
        let resolved = resolve()?;
        child_result::interpret_pending(workspace, agent_id, &worktree, &resolved.workflow, deps)?;
        cfg = Some(resolved);
    }

    // Warrant derives from the transcript tail alone (§2.3, §6): the
    // §5.2 head/body sits ahead of the tail and must not read as
    // user-side mail warranting a model call — and the transcript-only
    // composition keeps a no-op hop config-free (lazy resolution,
    // above).
    match warrant(&assembler::transcript(&worktree)?) {
        Warrant::NothingDue => {
            // §2.11 pin 1, closed by the release rule: the silent exit
            // is silent only over an inbox this hop's own last read
            // fully accounted for — a deposit that raced that read met a
            // Busy writer probe and is owed its launch by us.
            driver::release_then_reprobe(lock, workspace, agent_id, &seen, deps.launcher);
            Ok(AdvanceOutcome::NothingToDo)
        }
        Warrant::Unpaired => Err(Error::UnpairedToolUse {
            branch: agent_id.to_string(),
        }),
        Warrant::ModelCallDue => {
            let cfg = match cfg {
                Some(cfg) => cfg,
                None => resolve()?,
            };
            match hop::step(workspace, agent_id, &worktree, &cfg, deps)? {
                hop::StepOutcome::ToolsRan => Ok(AdvanceOutcome::ToolsPending(lock)),
                hop::StepOutcome::Terminal(epitaph) => {
                    // The shared §2.11 terminal tail ([`terminal::conclude`]
                    // — the same sequence as `run_exchange`'s): finish by
                    // epitaph value, terminal-lifecycle bindings (§6),
                    // release through the release rule (a racing deposit
                    // launches whatever the epitaph), then the
                    // epitaph-valued exit launches. No terminal compaction
                    // (§2.7 — the stage is deleted).
                    terminal::conclude(
                        workspace,
                        agent_id,
                        epitaph,
                        &cfg.workflow,
                        lock,
                        &seen,
                        deps,
                    )?;
                    Ok(AdvanceOutcome::Terminal)
                }
            }
        }
    }
}