Skip to content

Open-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.

9.3 KB
Raw Blame
//! What a person is told when something fails, and what a developer is told at the same time.
//!
//! TWO PARTS, ALWAYS, and this exists because one part is never enough for both readers. The
//! person needs a sentence about their situation and what to do next; whoever is debugging needs
//! the actual output, verbatim, including the bits that are only meaningful to them. Collapse them
//! and one of the two is failed: a plain sentence alone throws away the evidence, and raw engine
//! output alone is what put "pull access denied for openbot-agent-langgraph-agui, repository does
//! not exist or may require 'docker login'" in front of somebody who was setting up an app.
//!
//! The window shows `said` as the failure and keeps `detail` behind a disclosure, so the default
//! reading is the human one and nothing is lost.

use serde::Serialize;

#[derive(Clone, Debug, Serialize, PartialEq, Eq)]
#[serde(rename_all = "kebab-case")]
pub enum Connection {
    Model,
    Intelligence,
    Organization,
}

/// A failure, in both registers.
#[derive(Clone, Debug, Serialize, PartialEq, Eq)]
pub struct Problem {
    /// For the person. Their situation, and the next thing they can do about it.
    pub said: String,
    /// For whoever is debugging. Verbatim, and never shown as the headline.
    ///
    /// `None` where the plain sentence IS the whole truth — a refusal this deployment decided, with
    /// no underlying output behind it.
    pub detail: Option<String>,
    /// The credential operation that failed, never inferred from provider log text.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub connection: Option<Connection>,
    /// The full, verified Compose volume name offered for an explicit fresh-install reset.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub database_reset: Option<String>,
    /// A verified fresh-install reset of everything a previous installation left behind.
    /// Boxed and flattened: the window reads `leftover_reset` and `leftover_containers`.
    #[serde(flatten, skip_serializing_if = "Option::is_none")]
    pub leftover: Option<Box<LeftoverReset>>,
}

/// Exactly what one confirmed reset removes: the containers first, then the volumes.
#[derive(Clone, Debug, Default, Serialize, PartialEq, Eq)]
pub struct LeftoverReset {
    /// Every verified volume, the database included.
    #[serde(rename = "leftover_reset", skip_serializing_if = "Vec::is_empty")]
    pub volumes: Vec<String>,
    /// Stopped containers that still hold those volumes.
    #[serde(rename = "leftover_containers", skip_serializing_if = "Vec::is_empty")]
    pub containers: Vec<String>,
}

impl Problem {
    /// A refusal this deployment made itself, where there is nothing underneath to show.
    pub fn plain(said: impl Into<String>) -> Self {
        Self {
            said: said.into(),
            detail: None,
            connection: None,
            database_reset: None,
            leftover: None,
        }
    }

    /// A sentence for the person, with the real output kept beside it.
    pub fn with(said: impl Into<String>, detail: impl Into<String>) -> Self {
        let detail = detail.into();
        Self {
            said: said.into(),
            detail: (!detail.trim().is_empty()).then_some(detail),
            connection: None,
            database_reset: None,
            leftover: None,
        }
    }

    /// The volumes a confirmed reset removes, or none when no reset is offered.
    pub fn leftover_volumes(&self) -> &[String] {
        self.leftover.as_deref().map_or(&[], |reset| &reset.volumes)
    }

    /// The stopped containers a confirmed reset removes before those volumes.
    pub fn leftover_containers(&self) -> &[String] {
        self.leftover
            .as_deref()
            .map_or(&[], |reset| &reset.containers)
    }

    pub fn connection(mut self, connection: Connection) -> Self {
        self.connection = Some(connection);
        self
    }
}

/*
 * Every error that is still a bare string becomes a plain problem.
 *
 * So `?` keeps working on the paths that have not been given a sentence yet, and those read exactly
 * as they did before rather than losing their message during the conversion. What it does NOT do is
 * let a raw engine dump masquerade as a sentence: `said_about` below is what turns one of those into
 * both halves, and the call sites that produce engine output use it.
 */
impl From<String> for Problem {
    fn from(said: String) -> Self {
        Self::plain(said)
    }
}

impl From<&str> for Problem {
    fn from(said: &str) -> Self {
        Self::plain(said)
    }
}

/**
A sentence for engine output, chosen by what the output actually says.

Pure and tested, because these are the failures a first run hits and the sentence is the only part
the person reads. Anything unrecognised keeps a general sentence rather than a guess: being vague is
fixable, and being confidently wrong about somebody's machine is not.
*/
pub fn said_about(output: &str) -> String {
    let lower = output.to_lowercase();

    // The one this was written for. A pull that is refused reads as a permissions problem, and is
    // almost always an image this release did not publish.
    if lower.contains("pull access denied")
        || lower.contains("repository does not exist")
        || lower.contains("manifest unknown")
        || lower.contains("not found: manifest")
    {
        return "OpenBot could not download one of the parts it needs. That version may not have \
                been published yet. Check for an OpenBot update, and try again."
            .into();
    }
    if lower.contains("port is already allocated") || lower.contains("address already in use") {
        return "Something else on this computer is using a port OpenBot needs. Close it, or \
                restart the computer, and try again."
            .into();
    }
    if lower.contains("no space left") {
        return "This computer has run out of disk space, so OpenBot could not finish. Free some \
                space and try again."
            .into();
    }
    if lower.contains("cannot connect")
        || lower.contains("is the docker daemon running")
        || lower.contains("connection refused")
    {
        return "OpenBot cannot reach the container engine. Start Docker or Podman, wait for it to \
                finish starting, and try again."
            .into();
    }
    if lower.contains("timeout") || lower.contains("timed out") {
        return "That took too long and stopped. It is usually a slow or interrupted connection, \
                so trying again often works."
            .into();
    }
    if lower.contains("unauthorized") || lower.contains("permission denied") {
        return "OpenBot was refused permission for something it needed. The details below say \
                what, and are worth sending to whoever set this up."
            .into();
    }

    "Something went wrong while setting OpenBot up. The details below are worth sending to \
     whoever set this up."
        .into()
}

#[cfg(test)]
mod tests {
    use super::*;

    /// The failure this whole file exists for.
    #[test]
    fn a_refused_pull_reads_as_a_missing_release_not_a_login_problem() {
        let raw =
            "Error response from daemon: pull access denied for openbot-agent-langgraph-agui, \
                   repository does not exist or may require 'docker login'";
        let said = said_about(raw);
        assert!(said.contains("could not download"), "{said}");
        // The person is never told to run `docker login`, which is not a thing they have.
        assert!(!said.to_lowercase().contains("docker login"), "{said}");
        assert!(!said.contains("openbot-agent"), "{said}");
    }

    #[test]
    fn a_taken_port_says_so_in_words_somebody_can_act_on() {
        let said = said_about("Bind for 0.0.0.0:4202 failed: port is already allocated");
        assert!(said.contains("port OpenBot needs"), "{said}");
    }

    #[test]
    fn an_engine_that_is_not_running_says_to_start_it() {
        let said =
            said_about("Cannot connect to the Docker daemon at unix:///var/run/docker.sock.");
        assert!(said.contains("Start Docker or Podman"), "{said}");
    }

    /// Unrecognised output keeps a general sentence. Guessing at somebody's machine is worse than
    /// admitting the detail is where the answer is.
    #[test]
    fn something_unrecognised_stays_general_rather_than_guessing() {
        let said = said_about("frobnicator exploded (0x8007)");
        assert!(said.contains("Something went wrong"), "{said}");
    }

    /// Both halves, and the detail is never empty-but-present.
    #[test]
    fn a_problem_carries_both_registers() {
        let both = Problem::with("Plain thing.", "raw output");
        assert_eq!(both.said, "Plain thing.");
        assert_eq!(both.detail.as_deref(), Some("raw output"));

        let blank = Problem::with("Plain thing.", "   ");
        assert_eq!(blank.detail, None, "whitespace is not a detail");

        let refusal = Problem::plain("We will not do that.");
        assert_eq!(refusal.detail, None);
    }

    /// A bare string still converts, so paths without a sentence yet read as they always did.
    #[test]
    fn a_bare_string_becomes_a_plain_problem() {
        let problem: Problem = "bun was not found".to_string().into();
        assert_eq!(problem.said, "bun was not found");
        assert_eq!(problem.detail, None);
    }
}