quvyta-cli 0.1.0-alpha.5

//! The chat: one screen where the person writes, the reply streams in, and the actions the model
//! asks for are done, or shown and asked about first.
//!
//! A turn goes round like this. What the person wrote joins the conversation and a request goes
//! out on a task, which hands the reply back piece by piece. When the reply asks for tools, each
//! call is taken in order: reading, listing and searching are done at once; an edit or a command
//! is shown on a card and waits for the person. When every call has its result the results go
//! back to the model in the next request, until it ends its turn. Esc stops whatever is going on
//! and every call still waiting is answered as stopped, so the conversation stays one the API
//! accepts.

mod form;
mod updates;
mod view;

#[cfg(test)]
mod action_tests;
#[cfg(test)]
mod hostile_tests;
#[cfg(test)]
mod member_tests;
#[cfg(test)]
mod profile_tests;
#[cfg(test)]
mod request_tests;
#[cfg(test)]
mod sizes_tests;
#[cfg(test)]
mod tests;
#[cfg(test)]
mod turn_tests;
#[cfg(test)]
mod view_tests;

use std::collections::{HashMap, VecDeque};
use std::io;

use qframe::prelude::*;
use qframe::runtime::{Task, TaskId, Update};
use qframe::storage::{Ecosystem, Settings};

use crate::actions::{Action, Outcome, Preview, Workspace};
use crate::config::{self, Missing, Provider, Source, UpdateFolders};
use crate::conversation::{self, Call, Conversation};
use crate::instructions;
use crate::provider::{Delta, KeyError, ProviderError, Reply, Stop};
use crate::store::Store;

pub use form::{Field as FormField, ProviderForm};

/// The keys of the application, layered over the framework's.
pub const KEYMAP: &str = include_str!("../../keymap.toml");

/// How many requests one turn may make before it stops and says so. A model that keeps asking
/// for tools would otherwise go on spending the person's money without an end.
pub const MAX_ROUNDS: usize = 50;

/// How long a card stands in front of the person, with no key pressed and no click, before it
/// takes an answer. A card can come up while the person is typing their next message, and the
/// letter that allows it or the space and Enter that press a button would otherwise answer an
/// edit or a command they never saw.
pub const QUIET: std::time::Duration = std::time::Duration::from_millis(700);

/// What the model is told when the person declines an action.
const DECLINED: &str = "The person declined this action.";

/// What calls still waiting are answered with when the person stops the turn before they run.
const PERSON_STOPPED: &str = "Not done: the person stopped the turn.";

/// What the action being done is answered with when the person stops the turn: an edit may
/// already be written and a command may have done part of its work, so the model is not told it
/// was not done.
const STOPPED_WHILE_DOING: &str = "Stopped by the person while this was being done: it may have done part or all of its work. Check before relying on it.";

/// What a call is answered with when the reply that made it ends before it is taken.
const TURN_ENDED: &str = "Not done: the turn ended before this ran.";

/// Everything that can happen.
#[derive(Debug, Clone)]
pub enum Msg {
    /// The text in the writing field changed.
    Draft(String),
    /// The person sent what they wrote.
    Send,
    /// A piece of the reply of round `.0` arrived.
    Delta(u64, Delta),
    /// The reply of round `.0` is complete, or failed.
    Replied(u64, Result<Reply, ProviderError>),
    /// The action of round `.0` for call `.1` is done.
    Done(u64, String, Outcome),
    /// The end of the output of round `.0`'s command so far, while it runs.
    Tail(u64, String),
    /// Card `.0` has stood in front of the person without a key or a click for [`QUIET`]
    /// (`.1` true), or the next input came (`.1` false).
    Quiet(u64, bool),
    /// The person allows the action on the card.
    Allow,
    /// The person declines the action on the card.
    Deny,
    /// Stop the reply or the action going on.
    Stop,
    /// Put the conversation aside and start a new one.
    New,
    /// Open the provider form.
    OpenProvider,
    /// A field of the provider form changed.
    Form(FormField, String),
    /// Save the provider form.
    SaveProvider,
    /// Make the key file the form names readable by its owner alone.
    PrivateKeyFile,
    /// Close the provider form without saving.
    CloseProvider,
    /// A newer version of qcli is out.
    NewVersion(Update),
}

/// What the chat is doing.
#[derive(Debug, Clone, PartialEq, Default)]
pub enum Phase {
    /// Waiting for the person to write.
    #[default]
    Idle,
    /// A reply is streaming in.
    Replying,
    /// An action waits for the person's answer.
    Asking {
        /// The call.
        call: Call,
        /// The action it asks for.
        action: Action,
        /// What it would do.
        preview: Preview,
        /// Whether the card takes an answer yet: it does once it has stood in front of the person
        /// for [`QUIET`] with no key pressed.
        ready: bool,
    },
    /// An action is being done.
    Acting {
        /// The call.
        call: Call,
        /// The action.
        action: Action,
    },
}

/// Something the screen says under the conversation until the next turn.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Notice {
    /// The provider could not be asked or did not answer.
    Provider(String),
    /// A field of the provider settings is empty.
    Unset,
    /// The key file gave no key.
    Key(KeyError),
    /// The person stopped the turn.
    Stopped,
    /// The reply ran out of tokens.
    Cut,
    /// The turn made as many requests as one may.
    Rounds,
    /// The conversation could not be saved.
    Unsaved(String),
    /// The person asked for the provider settings, and the provider is the QCode profile's.
    Profile,
}

/// What the current turn has cost: the tokens the provider counted as read and as written over
/// every reply of it. The person pays per token, and one turn is many requests, each of which
/// carries the whole conversation, so a turn's own total is what they want to see rather than
/// what any one reply said.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
struct Tokens {
    /// The tokens the replies of the turn read between them.
    read: u64,
    /// The tokens the replies of the turn wrote between them.
    written: u64,
}

impl Tokens {
    /// Adds what one reply counted. A reply that counted neither is worth nothing to the sum: the
    /// provider said nothing, and guessing a zero would say the turn was cheaper than it was.
    fn add(&mut self, reply: &Reply) {
        self.read += reply.input_tokens.unwrap_or(0);
        self.written += reply.output_tokens.unwrap_or(0);
    }

    /// Whether the turn used a token at all, which is what decides whether the screen says so.
    fn any(&self) -> bool {
        self.read + self.written > 0
    }
}

/// A piece of the reply as it streams in.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Live {
    /// Thinking.
    Thinking(String),
    /// Text.
    Text(String),
    /// A tool call by its tool's name.
    Call(String),
}

/// The application.
pub struct QCli {
    workspace: Workspace,
    store: Store,
    conversation: Conversation,
    settings: Settings,
    provider: Provider,
    draft: String,
    phase: Phase,
    live: Vec<Live>,
    /// The end of what the command being run has written so far, shown under its indicator.
    tail: String,
    /// The calls of the last reply still to be taken, and the results of those taken.
    queue: VecDeque<Call>,
    results: Vec<Value>,
    /// What each edit and command showed before it was allowed, by call id.
    previews: HashMap<String, Preview>,
    /// Requests made in the current turn.
    rounds: usize,
    /// The tokens the current turn has cost. They are said once it is over and are never saved:
    /// what a turn cost is the person's own business on this screen, not part of the thread.
    tokens: Tokens,
    /// The number of the current round. A message of an earlier one, which arrives after the
    /// person stopped it, is ignored.
    round: u64,
    task: Option<TaskId>,
    notice: Option<Notice>,
    form: Option<ProviderForm>,
    /// The number of the card shown last, so the quiet a card waits for is its own.
    card: u64,
    /// The number of the turn, part of the conversation view's id: a new turn opens the view at
    /// its end even when the person had scrolled up to read.
    turn: u64,
    /// Where the ecosystem's update notice looks; `None` asks nothing.
    updates: Option<UpdateFolders>,
    /// Whether the folder has an `AGENTS.md`, looked at when qcli opens and at every message, so
    /// drawing a frame never reads the disk.
    agents: bool,
    /// The saved answers as parsed and laid out documents, so a frame of a long conversation
    /// does not parse every answer again.
    answers: view::Answers,
}

type Value = serde_json::Value;

impl QCli {
    /// The chat in `workspace`, going on with the conversation `store` keeps, talking to the
    /// provider in `settings`. The provider form opens at once when the provider is not set up.
    #[must_use]
    pub fn new(workspace: Workspace, store: Store, settings: Settings) -> Self {
        let provider = Provider::from_settings(&settings);
        let form = provider.missing_field().is_some().then(|| ProviderForm::from_provider(&provider));
        let mut store = store;
        let conversation = store.load();
        let agents = instructions::agents(workspace.root()).is_some();
        Self {
            agents,
            answers: view::Answers::default(),
            workspace,
            store,
            conversation,
            settings,
            provider,
            draft: String::new(),
            phase: Phase::Idle,
            live: Vec::new(),
            tail: String::new(),
            queue: VecDeque::new(),
            results: Vec::new(),
            previews: HashMap::new(),
            rounds: 0,
            tokens: Tokens::default(),
            round: 0,
            task: None,
            notice: None,
            form,
            card: 0,
            turn: 0,
            updates: None,
        }
    }

    /// The same chat on `provider`, which the QCode profile qcli runs in described, in place of
    /// the one in the settings. The provider form never opens on it: the profile is where it is
    /// changed.
    #[must_use]
    pub fn on_profile(mut self, provider: Provider) -> Self {
        self.provider = provider;
        self.form = None;
        self
    }

    /// The conversation so far.
    #[must_use]
    pub fn conversation(&self) -> &Conversation {
        &self.conversation
    }

    /// What the chat is doing.
    #[must_use]
    pub fn phase(&self) -> &Phase {
        &self.phase
    }

    /// What the screen says under the conversation, if anything.
    #[must_use]
    pub fn notice(&self) -> Option<&Notice> {
        self.notice.as_ref()
    }

    fn busy(&self) -> bool {
        self.phase != Phase::Idle
    }

    /// Gives the writing field the focus: after a card is answered its buttons are gone, and the
    /// next key the person presses belongs to the field.
    fn to_input() -> Command<Msg> {
        Command::focus(view::INPUT)
    }

    fn save(&mut self) {
        if let Err(error) = self.store.save(&self.conversation) {
            self.notice = Some(Notice::Unsaved(error.to_string()));
        }
    }

    fn send(&mut self) -> Command<Msg> {
        let text = self.draft.trim().to_owned();
        if text.is_empty() || self.busy() {
            return Command::none();
        }
        if self.provider.missing_field().is_some() {
            self.form = Some(ProviderForm::from_provider(&self.provider));
            return Command::none();
        }
        self.draft.clear();
        self.notice = None;
        self.agents = instructions::agents(self.workspace.root()).is_some();
        self.conversation.say(&text);
        self.save();
        // What a turn costs is the turn's own: these sums start again here, where the request
        // count does, so the line under the conversation never carries an earlier turn's numbers.
        self.rounds = 0;
        self.tokens = Tokens::default();
        self.turn += 1;
        Command::batch([self.ask(), Self::to_input()])
    }

    /// Sends the conversation as it is and waits for the reply.
    fn ask(&mut self) -> Command<Msg> {
        let endpoint = match self.provider.endpoint() {
            Ok(endpoint) => endpoint,
            Err(Missing::Field(_)) => return self.stop_with(Notice::Unset),
            Err(Missing::Key(error)) => return self.stop_with(Notice::Key(error)),
        };
        if self.rounds >= MAX_ROUNDS {
            return self.stop_with(Notice::Rounds);
        }
        self.rounds += 1;
        self.round += 1;
        self.live.clear();
        self.phase = Phase::Replying;
        let round = self.round;
        let body = instructions::body(&self.conversation, &instructions::system(self.workspace.root()));
        let task = Task::new("reply", move |cx| {
            let reply = endpoint.stream(&body, &mut |delta| cx.send(Msg::Delta(round, delta)), &|| cx.is_cancelled());
            Ok(Msg::Replied(round, reply))
        });
        self.task = Some(task.id());
        Command::task(task)
    }

    fn stop_with(&mut self, notice: Notice) -> Command<Msg> {
        self.phase = Phase::Idle;
        self.notice = Some(notice);
        Self::to_input()
    }

    fn replied(&mut self, reply: Result<Reply, ProviderError>) -> Command<Msg> {
        self.task = None;
        self.live.clear();
        let reply = match reply {
            Ok(reply) => reply,
            Err(error) => return self.stop_with(Notice::Provider(error.to_string())),
        };
        // What this request cost goes on the turn's total, whether the reply ends the turn or
        // asks for tools: one turn is many requests and the person pays for all of them.
        self.tokens.add(&reply);
        let stop = reply.stop.clone();
        self.conversation.reply(reply.content);
        self.save();
        match stop {
            Stop::ToolUse => {
                self.queue = self.conversation.open_calls().into();
                self.results.clear();
                self.next()
            }
            Stop::MaxTokens => {
                self.answer_untaken();
                self.stop_with(Notice::Cut)
            }
            Stop::EndTurn | Stop::Other(_) => {
                self.answer_untaken();
                self.phase = Phase::Idle;
                Self::to_input()
            }
        }
    }

    /// Answers the calls of this reply that the turn is not going to take, so the next request is
    /// one the API accepts: a `tool_use` whose result never comes is refused, and it would be
    /// refused again on every request after that, leaving the person with a thread that cannot
    /// go on. A reply that ends in a way qcli does not know leaves its calls this way.
    fn answer_untaken(&mut self) {
        let open = self.conversation.open_calls();
        if open.is_empty() {
            return;
        }
        let results: Vec<Value> = open
            .iter()
            .map(|call| {
                // A call that names no tool could never have been done, so that is what it is
                // told; one that could have been is told the turn ended first.
                let reason = Action::from_call(&call.name, &call.input).err().unwrap_or_else(|| TURN_ENDED.to_owned());
                conversation::result(&call.id, &reason, true)
            })
            .collect();
        self.conversation.results(results);
        self.save();
    }

    /// Takes the next call of the reply, or sends the results when every call has one.
    fn next(&mut self) -> Command<Msg> {
        let Some(call) = self.queue.pop_front() else {
            self.conversation.results(std::mem::take(&mut self.results));
            self.save();
            return Command::batch([self.ask(), Self::to_input()]);
        };
        let action = match Action::from_call(&call.name, &call.input) {
            Ok(action) => action,
            Err(reason) => return self.answer(&call.id, &reason, true),
        };
        if !action.needs_approval() {
            return self.act(call, action);
        }
        match self.workspace.preview(&action) {
            Ok(preview) => {
                self.previews.insert(call.id.clone(), preview.clone());
                self.card += 1;
                self.phase = Phase::Asking { call, action, preview, ready: false };
                Command::none()
            }
            Err(reason) => self.answer(&call.id, &reason, true),
        }
    }

    /// Records the result of call `id` and goes on with the next.
    fn answer(&mut self, id: &str, text: &str, is_error: bool) -> Command<Msg> {
        self.results.push(conversation::result(id, text, is_error));
        self.next()
    }

    fn act(&mut self, call: Call, action: Action) -> Command<Msg> {
        let workspace = self.workspace.clone();
        let round = self.round;
        let id = call.id.clone();
        let doing = action.clone();
        let shown = self.previews.get(&call.id).cloned();
        let task = Task::new("action", move |cx| {
            let mut on_tail = |tail: &str| cx.send(Msg::Tail(round, tail.to_owned()));
            let outcome = workspace.perform_watching(&doing, shown.as_ref(), &|| cx.is_cancelled(), &mut on_tail);
            Ok(Msg::Done(round, id, outcome))
        });
        self.tail.clear();
        self.task = Some(task.id());
        self.phase = Phase::Acting { call, action };
        Command::batch([Command::task(task), Self::to_input()])
    }

    /// Stops what is going on. A reply keeps the text that had come; calls still waiting are
    /// answered as stopped.
    fn stop(&mut self) -> Command<Msg> {
        let cancel = self.task.take().map_or_else(Command::none, Command::cancel_task);
        self.round += 1;
        match std::mem::take(&mut self.phase) {
            Phase::Idle => return cancel,
            Phase::Replying => {
                let text: String = self
                    .live
                    .iter()
                    .filter_map(|live| if let Live::Text(text) = live { Some(text.as_str()) } else { None })
                    .collect();
                if !text.trim().is_empty() {
                    self.conversation.reply(vec![serde_json::json!({"type": "text", "text": text})]);
                }
                self.live.clear();
            }
            Phase::Asking { call, .. } => self.answer_stopped(&call, PERSON_STOPPED),
            Phase::Acting { call, .. } => self.answer_stopped(&call, STOPPED_WHILE_DOING),
        }
        self.save();
        self.notice = Some(Notice::Stopped);
        Command::batch([cancel, Self::to_input()])
    }

    /// Answers `call`, the one on the card or being done when the person stopped the turn, with
    /// `sentence`, and every call still waiting after it as not done.
    fn answer_stopped(&mut self, call: &Call, sentence: &str) {
        self.results.push(conversation::result(&call.id, sentence, true));
        for waiting in std::mem::take(&mut self.queue) {
            self.results.push(conversation::result(&waiting.id, PERSON_STOPPED, true));
        }
        self.conversation.results(std::mem::take(&mut self.results));
    }

    fn new_conversation(&mut self) -> Command<Msg> {
        let stopped = self.stop();
        if let Err(error) = self.store.put_aside() {
            self.notice = Some(Notice::Unsaved(error.to_string()));
            return stopped;
        }
        self.conversation = Conversation::default();
        self.agents = instructions::agents(self.workspace.root()).is_some();
        self.previews.clear();
        self.notice = None;
        // The turn that was going on is over, and so is what it had cost: the next turn is
        // counted from nothing.
        self.tokens = Tokens::default();
        self.turn += 1;
        Command::batch([stopped, Self::to_input()])
    }

    fn save_provider(&mut self) -> Command<Msg> {
        if self.provider.source == Source::Profile {
            return Command::none();
        }
        let Some(form) = self.form.as_mut() else { return Command::none() };
        let Some(provider) = form.check() else {
            return form.errors().focus_first();
        };
        provider.write(&mut self.settings);
        if let Err(error) = self.settings.save() {
            form.failed(&error);
            return Command::none();
        }
        self.provider = provider;
        self.form = None;
        if matches!(self.notice, Some(Notice::Unset | Notice::Key(_))) {
            self.notice = None;
        }
        Self::to_input()
    }
}

impl App for QCli {
    type Msg = Msg;

    fn init(&mut self) -> Command<Msg> {
        let focus = match &self.form {
            Some(_) => Command::focus(form::FIRST),
            None => Self::to_input(),
        };
        Command::batch([focus, self.ask_for_update()])
    }

    fn update(&mut self, msg: Msg) -> Command<Msg> {
        match msg {
            Msg::Draft(text) => {
                self.draft = text;
                Command::none()
            }
            Msg::Send => self.send(),
            Msg::Delta(round, delta) if round == self.round => {
                match (delta, self.live.last_mut()) {
                    (Delta::Text(piece), Some(Live::Text(text)))
                    | (Delta::Thinking(piece), Some(Live::Thinking(text))) => {
                        text.push_str(&piece);
                    }
                    (Delta::Text(piece), _) => self.live.push(Live::Text(piece)),
                    (Delta::Thinking(piece), _) => self.live.push(Live::Thinking(piece)),
                    (Delta::ToolCall(name), _) => self.live.push(Live::Call(name)),
                }
                Command::none()
            }
            Msg::Replied(round, reply) if round == self.round => self.replied(reply),
            Msg::Tail(round, tail) if round == self.round => {
                self.tail = tail;
                Command::none()
            }
            Msg::Done(round, id, outcome) if round == self.round => {
                self.tail.clear();
                self.task = None;
                self.answer(&id, &outcome.text, outcome.is_error)
            }
            Msg::Delta(..) | Msg::Replied(..) | Msg::Done(..) | Msg::Tail(..) => Command::none(),
            Msg::Quiet(card, true) if card == self.card => match &mut self.phase {
                // No button takes the focus: Enter and space, the keys that send a message and
                // separate its words, answer nothing, and a person scrolled up to read is not
                // pulled down to the card.
                Phase::Asking { ready, .. } => {
                    *ready = true;
                    Command::none()
                }
                _ => Command::none(),
            },
            Msg::Quiet(..) => Command::none(),
            Msg::Allow => match std::mem::take(&mut self.phase) {
                Phase::Asking { call, action, ready: true, .. } => self.act(call, action),
                other => {
                    self.phase = other;
                    Command::none()
                }
            },
            Msg::Deny => match std::mem::take(&mut self.phase) {
                Phase::Asking { call, ready: true, .. } => {
                    self.phase = Phase::Idle;
                    self.answer(&call.id, DECLINED, true)
                }
                other => {
                    self.phase = other;
                    Command::none()
                }
            },
            Msg::Stop => self.stop(),
            Msg::New => self.new_conversation(),
            Msg::OpenProvider if self.provider.source == Source::Profile => {
                self.notice = Some(Notice::Profile);
                Command::none()
            }
            Msg::OpenProvider => {
                self.form = Some(ProviderForm::from_provider(&self.provider));
                Command::focus(form::FIRST)
            }
            Msg::Form(field, value) => {
                if let Some(form) = self.form.as_mut() {
                    form.set(field, value);
                }
                Command::none()
            }
            Msg::SaveProvider => self.save_provider(),
            Msg::PrivateKeyFile => {
                if let Some(form) = self.form.as_mut() {
                    form.make_key_file_private();
                }
                Command::none()
            }
            Msg::NewVersion(update) => Command::toast(update.toast()),
            Msg::CloseProvider => {
                self.form = None;
                Self::to_input()
            }
        }
    }

    fn action(&self, name: &str) -> Option<Msg> {
        if self.form.is_some() {
            return None;
        }
        match name {
            "stop" if self.busy() => Some(Msg::Stop),
            "allow" if matches!(self.phase, Phase::Asking { ready: true, .. }) => Some(Msg::Allow),
            "deny" if matches!(self.phase, Phase::Asking { ready: true, .. }) => Some(Msg::Deny),
            "new" => Some(Msg::New),
            "provider" => Some(Msg::OpenProvider),
            _ => None,
        }
    }

    fn view(&self, ui: &mut View<'_, Msg>) {
        view::view(self, ui);
    }
}

/// Opens qcli in the folder it was started in.
///
/// # Errors
///
/// When the folder cannot be read, or the terminal cannot be used.
pub fn run() -> io::Result<()> {
    let folder = std::env::current_dir()?;
    let workspace = Workspace::new(&folder)?;
    // Conversations hold what was read and run, so they are never kept in a folder every user of
    // the machine can reach, such as the system's temporary one.
    let conversations = Ecosystem::QUVYTA
        .state_dir(config::APP)
        .ok_or_else(|| {
            io::Error::new(
                io::ErrorKind::NotFound,
                "qcli keeps its conversations in the state folder (XDG_STATE_HOME, or ~/.local/state), and neither is known",
            )
        })?
        .join("conversations");
    let store = Store::new(&conversations, workspace.root());
    let app = opening(workspace, store, config::load(), |name| std::env::var(name).ok(), UpdateFolders::here())
        .map_err(|error| io::Error::new(io::ErrorKind::InvalidInput, error))?;
    runtime(app).run()
}

/// The chat `run()` opens: on the provider a QCode profile describes in the environment `read`
/// gives, when it describes one, and on the one in `settings` otherwise.
///
/// In a profile the ecosystem's update notice is not asked for: qcli came with the profile's
/// image and is renewed when the image is rebuilt in QCode, so "a newer version is out" would ask
/// the person for something they cannot do in the tab.
fn opening(
    workspace: Workspace,
    store: Store,
    settings: Settings,
    read: impl Fn(&str) -> Option<String>,
    updates: Option<UpdateFolders>,
) -> Result<QCli, config::ProfileError> {
    let app = QCli::new(workspace, store, settings);
    Ok(match Provider::from_environment(read)? {
        Some(provider) => app.on_profile(provider),
        None => app.update_notice(updates),
    })
}

/// The runtime `run()` starts: qcli as a member of the ecosystem, with its own keys and language
/// files. The member start reads qcli's own settings file and the ecosystem's and follows both
/// while qcli runs. Tests open the same runtime without a terminal, so a line dropped here shows.
fn runtime(app: QCli) -> Runtime<QCli> {
    let mut runtime = Runtime::new(app).member(Ecosystem::QUVYTA, config::APP).keymap_source("keymap.toml", KEYMAP);
    for &(file, text) in crate::locales() {
        runtime = runtime.locale_source(file, text);
    }
    runtime
}