haest-cli 0.4.0

haest, the command line agent
//! One line from the human while a turn runs: the answer to an approval ask.
//!
//! Only what is typed once the question is on the screen answers it. The
//! prompter reads only after the terminal has drawn the question, and
//! [`read_answer`] first drops what was typed and not read yet: a line typed
//! at a question the model's own text drew, or a key left at an ask given up.
//! On a terminal the line is then read from it a byte at a time, so nothing
//! past the line is taken, and no buffer between the terminal and haest (std's
//! `Stdin` keeps one) can hold a byte typed before.
//!
//! The read is WITHDRAWABLE. An ask the gate gives up on (an interrupt, the
//! timeout) must not leave a reader blocked on stdin, or it would swallow the
//! next line typed at the REPL prompt.

use std::{
    io::{BufRead, IsTerminal},
    os::fd::RawFd,
    sync::{
        Arc,
        atomic::{AtomicBool, Ordering},
    },
};

/// Why a human cannot answer an approval here.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum NoTerminal {
    /// stdin is not a terminal: nobody types an answer.
    Stdin,
    /// stderr, where the question shows, is not a terminal (`2>log`): it
    /// would be asked where nobody sees it.
    Stderr,
    /// With --json the question is a line on stdout, and stdout is a
    /// regular file (`> out.jsonl`): no screen shows it. (A pipe may: `| jq`.)
    Stdout,
}

impl std::fmt::Display for NoTerminal {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(match self {
            Self::Stdin => "there is no terminal to ask on",
            Self::Stderr => "stderr, where haest asks, is not a terminal",
            Self::Stdout => "stdout, where haest asks with --json, is a file",
        })
    }
}

/// Can a human answer here: stdin is a terminal, and the question shows
/// where someone can read it: on stderr, a terminal; with `json` a line on
/// stdout, which must not be a regular file.
pub(crate) fn interactive(json: bool) -> Result<(), NoTerminal> {
    if !std::io::stdin().is_terminal() {
        Err(NoTerminal::Stdin)
    } else if json && crate::render::is_a_file(&std::io::stdout()) {
        Err(NoTerminal::Stdout)
    } else if !json && !std::io::stderr().is_terminal() {
        Err(NoTerminal::Stderr)
    } else {
        Ok(())
    }
}

/// Raised when the read's future is dropped: the blocked reader then stops.
struct Withdraw(Arc<AtomicBool>);

impl Drop for Withdraw {
    fn drop(&mut self) {
        self.0.store(true, Ordering::Relaxed);
    }
}

/// The answer to the question just drawn: a line typed from now on. None
/// when stdin closed or the read was withdrawn.
pub(crate) async fn read_answer() -> Option<String> {
    drop_typed_ahead();
    let stop = Arc::new(AtomicBool::new(false));
    let _withdraw = Withdraw(stop.clone());
    tokio::task::spawn_blocking(move || read_line_until(&stop))
        .await
        .ok()
        .flatten()
}

/// A line from stdin through std's buffer: for a pipe or a file (a parent
/// or a test writing answers), where one read can hold many lines.
fn read_one() -> Option<String> {
    let mut line = String::new();
    match std::io::stdin().lock().read_line(&mut line) {
        Ok(0) | Err(_) => None,
        Ok(_) => Some(line),
    }
}

fn read_line_until(stop: &AtomicBool) -> Option<String> {
    if std::io::stdin().is_terminal() {
        terminal_line(libc::STDIN_FILENO, stop)
    } else if readable(libc::STDIN_FILENO, stop) {
        read_one()
    } else {
        None
    }
}

/// Waits in 100 ms slices until `fd` has something to read, so a withdrawn
/// read lets go of stdin before the REPL reads it again. False once `stop`
/// is raised, or when the wait fails.
fn readable(fd: RawFd, stop: &AtomicBool) -> bool {
    let mut pollfd = libc::pollfd {
        fd,
        events: libc::POLLIN,
        revents: 0,
    };
    while !stop.load(Ordering::Relaxed) {
        #[expect(unsafe_code, reason = "poll(2) waits on stdin without taking it")]
        // SAFETY: one valid, initialised pollfd, and the count says one.
        let ready = unsafe { libc::poll(&raw mut pollfd, 1, 100) };
        if ready > 0 {
            return true;
        }
        let interrupted = std::io::Error::last_os_error().kind() == std::io::ErrorKind::Interrupted;
        if ready < 0 && !interrupted {
            return false;
        }
    }
    false
}

/// A line from the terminal `fd`, a byte at a time: what follows the line
/// stays in the terminal, where [`drop_typed_ahead`] reaches it, and a
/// withdrawn read lets go between any two bytes (a key typed, then Ctrl+D,
/// hands over half a line). None when the terminal closed (Ctrl+D on an
/// empty line), the read failed or it was withdrawn.
fn terminal_line(fd: RawFd, stop: &AtomicBool) -> Option<String> {
    let mut line = Vec::new();
    while line.last() != Some(&b'\n') {
        if !readable(fd, stop) {
            return None;
        }
        let mut byte = 0_u8;
        #[expect(
            unsafe_code,
            reason = "read(2) of one byte; std's Stdin would buffer what follows"
        )]
        // SAFETY: a valid one-byte buffer, and the count says one.
        let n = unsafe { libc::read(fd, (&raw mut byte).cast(), 1) };
        match n {
            1 => line.push(byte),
            // Ctrl+D: on an empty line the terminal closed; after a key or
            // two it is the end of a line with no newline.
            0 if line.is_empty() => return None,
            0 => break,
            _ => {
                let kind = std::io::Error::last_os_error().kind();
                if !matches!(
                    kind,
                    std::io::ErrorKind::Interrupted | std::io::ErrorKind::WouldBlock
                ) {
                    return None;
                }
            }
        }
    }
    Some(String::from_utf8_lossy(&line).into_owned())
}

/// Drops what was typed at the terminal and not read yet, a whole line or
/// keys with no Enter: only what is typed from now on answers. Stdin that
/// is not a terminal (a pipe a parent or a test writes answers into) keeps
/// what is in it.
fn drop_typed_ahead() {
    if std::io::stdin().is_terminal() {
        drop_typed_ahead_on(libc::STDIN_FILENO);
    }
}

fn drop_typed_ahead_on(fd: RawFd) {
    #[expect(unsafe_code, reason = "tcflush(3) drops a terminal's unread input")]
    // SAFETY: no memory is passed; a descriptor that is not a terminal is an
    // error, and nothing is dropped then.
    unsafe {
        libc::tcflush(fd, libc::TCIFLUSH);
    }
}

#[cfg(test)]
mod tests;