//! Records the version this binary was published as.

//!

//! The crate manifest names the version of the source; `ops/release-cli.sh`

//! names the version of the release, and for a release candidate the two

//! differ. `oa update` compares what the binary reports against what the

//! channel pointer resolves to, so the binary has to report the name it was

//! published under or the comparison is meaningless.

//!

//! Cargo does not otherwise track environment variables read through

//! `option_env!`, so a second build with a different version would reuse the

//! first one's artifact. This declares the dependency.

fn main() {

    println!("cargo:rerun-if-env-changed=OPENAGENTS_CLI_RELEASE_VERSION");

}

use clap::{Args, Parser, Subcommand};

#[derive(Parser, Debug)]

#[command(name = "oa", version, about = "OpenAgents Rust CLI", long_about = None)]

#[command(name = "oa", version = crate::VERSION, about = "OpenAgents Rust CLI", long_about = None)]

pub struct Cli {

    #[command(subcommand)]

    pub command: Commands,

    Api(ApiArgs),

    /// Trace inspection and session export

    Trace(TraceArgs),

    /// Replace this binary with the release the channel names

    #[command(alias = "self-update")]

    Update(UpdateArgs),

}

#[derive(Args, Debug)]

pub struct UpdateArgs {

    #[arg(long, help = "Release channel to resolve (default: stable)")]

    pub channel: Option<String>,

    #[arg(long, help = "Install this exact version instead of resolving a channel")]

    pub version: Option<String>,

    #[arg(long, help = "Report what the channel names without downloading anything")]

    pub check: bool,

    #[arg(long, help = "Reinstall even when the channel names the running version")]

    pub force: bool,

}

#[derive(Args, Debug)]

                println!("Redacted size: {} bytes", sanitized.len());

            }

        },

        Commands::Update(update) => {

            crate::update::run(update.channel, update.version, update.check, update.force).await?;

        }

    }

    Ok(())

}

/// The version this binary was published as.

///

/// The crate manifest names the version of the source. A release candidate is

/// built from a crate at `0.1.0` and published as `0.1.0-rc.2`, and it is the

/// published name that `oa update` compares against the channel pointer, so

/// `ops/release-cli.sh` threads that name in at build time. A build that is

/// not a release falls back to the manifest, which is the honest answer for

/// one.

pub const VERSION: &str = match option_env!("OPENAGENTS_CLI_RELEASE_VERSION") {

    Some(version) => version,

    None => env!("CARGO_PKG_VERSION"),

};

pub mod acp;

pub mod api_passthrough;

pub mod auth;

pub mod trace;

pub mod tracker;

pub mod tui;

pub mod update;

//! `oa update` — replace this binary with the one the channel names.

//!

//! This is the installer's contract read from the other end. The script at

//! <https://openagents.com/install.sh> resolves a channel pointer to a version,

//! downloads `openagents-<version>-<platform>`, fetches

//! `SHA256SUMS-<version>` over a separate request, refuses when the sums file

//! is missing or names no entry for the artifact, refuses when the digest

//! disagrees, and only then makes the bytes executable. Every one of those

//! refusals is repeated here, because an update path that verifies less than

//! the install path would mean the second binary a reader receives is held to

//! a lower standard than the first.

//!

//! Two things this knows that the shell script has to work out at runtime. The

//! platform is decided at compile time: a binary knows its own architecture and

//! its own C library, so there is no libc probe here and no way for one to be

//! wrong. And the path to replace comes from the running process rather than

//! from a convention about where the installer puts things, so an `oa` invoked

//! through the symlinks the installer leaves in `~/.openagents/bin` updates the

//! file those symlinks point at and they keep pointing at it.

use std::path::{Path, PathBuf};

use sha2::{Digest, Sha256};

/// Where releases are published. Overridable so the flow can be exercised

/// against a fixture server without pointing a test at the real one.

pub const DEFAULT_BASE_URL: &str = "https://openagents.com/releases";

/// The channel a reader who names none is asking for.

pub const DEFAULT_CHANNEL: &str = "stable";

#[derive(Debug)]

pub enum UpdateError {

    /// This build has no published artifact to update to.

    UnsupportedPlatform { os: String, arch: String },

    /// The channel pointer could not be read.

    ChannelUnreadable { channel: String, detail: String },

    /// The channel resolved to something that is not a version.

    ChannelNotAVersion { channel: String, body: String },

    /// A version was named that the release naming grammar does not admit.

    InvalidVersion(String),

    /// The artifact itself could not be fetched.

    ArtifactUnavailable { name: String, detail: String },

    /// The sums file could not be fetched. Nothing is installed unverified.

    SumsUnavailable { version: String, detail: String },

    /// The sums file exists but names no entry for this artifact.

    SumsMissingEntry { version: String, name: String },

    /// The bytes that arrived are not the bytes the release published.

    DigestMismatch {

        name: String,

        expected: String,

        actual: String,

    },

    /// The binary could not be replaced.

    ReplaceFailed { path: PathBuf, detail: String },

}

impl std::fmt::Display for UpdateError {

    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {

        match self {

            Self::UnsupportedPlatform { os, arch } => write!(

                formatter,

                "no release is published for {os}/{arch}, so there is nothing to update to"

            ),

            Self::ChannelUnreadable { channel, detail } => write!(

                formatter,

                "could not resolve the '{channel}' channel: {detail}"

            ),

            Self::ChannelNotAVersion { channel, body } => write!(

                formatter,

                "the '{channel}' channel returned something that is not a version: {body}"

            ),

            Self::InvalidVersion(version) => write!(

                formatter,

                "invalid version: {version} (expected X.Y.Z or X.Y.Z-suffix)"

            ),

            Self::ArtifactUnavailable { name, detail } => {

                write!(formatter, "could not download {name}: {detail}")

            }

            Self::SumsUnavailable { version, detail } => write!(

                formatter,

                "could not download SHA256SUMS-{version} ({detail}); \

                 refusing to install unverified bytes"

            ),

            Self::SumsMissingEntry { version, name } => write!(

                formatter,

                "SHA256SUMS-{version} names no entry for {name}; refusing to install"

            ),

            Self::DigestMismatch {

                name,

                expected,

                actual,

            } => write!(

                formatter,

                "checksum mismatch for {name}\n  expected {expected}\n  actual   {actual}"

            ),

            Self::ReplaceFailed { path, detail } => {

                write!(formatter, "could not replace {}: {detail}", path.display())

            }

        }

    }

}

impl std::error::Error for UpdateError {}

/// The platform segment of the artifact name for the build this code is

/// compiled into.

///

/// The installer works this out at runtime from `uname` and a search for the

/// glibc loader. A binary does not have to: it was built for exactly one

/// target, and `target_env = "musl"` is settled by the toolchain that produced

/// it. `None` means this build has no published counterpart, which is a

/// clearer thing to say than a request for a URL that will 404.

pub fn platform() -> Option<String> {

    let os = match std::env::consts::OS {

        "macos" => "macos",

        "linux" => "linux",

        "windows" => "windows",

        _ => return None,

    };

    let arch = match std::env::consts::ARCH {

        "x86_64" => "x86_64",

        "aarch64" => "aarch64",

        _ => return None,

    };

    // Only Linux is published in two libc flavors. The glibc artifact keeps

    // the unsuffixed name it has always had; musl is the one that carries a

    // suffix, exactly as the installer asks for it.

    let libc = if os == "linux" && cfg!(target_env = "musl") {

        "-musl"

    } else {

        ""

    };

    Some(format!("{os}-{arch}{libc}"))

}

/// The grammar `ops/release-cli.sh` and the installer both apply. A version

/// one of them accepts and another rejects is a release nobody can ask for.

pub fn valid_version(value: &str) -> bool {

    let (core, suffix) = match value.split_once('-') {

        Some((core, suffix)) => (core, Some(suffix)),

        None => (value, None),

    };

    let mut parts = core.split('.');

    let numeric = |part: Option<&str>| {

        part.is_some_and(|part| !part.is_empty() && part.bytes().all(|byte| byte.is_ascii_digit()))

    };

    if !numeric(parts.next()) || !numeric(parts.next()) || !numeric(parts.next()) {

        return false;

    }

    if parts.next().is_some() {

        return false;

    }

    match suffix {

        None => true,

        Some(suffix) => {

            !suffix.is_empty()

                && suffix

                    .bytes()

                    .all(|byte| byte.is_ascii_alphanumeric() || byte == b'.' || byte == b'_')

        }

    }

}

/// Read one digest out of a `SHA256SUMS` file.

///

/// The installer's lookup is `awk '$2 == name || $2 == "*" name'`, and the

/// leading `*` is the binary-mode marker `sha256sum` writes. This is that

/// lookup, so an entry either tool accepts is an entry both accept.

pub fn digest_for(sums: &str, name: &str) -> Option<String> {

    sums.lines().find_map(|line| {

        let mut fields = line.split_whitespace();

        let digest = fields.next()?;

        let entry = fields.next()?;

        if entry == name || entry.strip_prefix('*') == Some(name) {

            Some(digest.to_string())

        } else {

            None

        }

    })

}

/// The published object name for a version and platform.

///

/// The artifact URL never carries a file extension, on any platform. The

/// `SHA256SUMS` entry for Windows *does*, because the installer appends `.exe`

/// to the name it searches for after downloading a URL without one. The two

/// disagree by design and `ops/release-cli.sh` publishes them that way, so

/// both spellings live here rather than being guessed at a call site.

pub fn artifact_name(version: &str, platform: &str) -> String {

    format!("openagents-{version}-{platform}")

}

pub fn sums_entry_name(version: &str, platform: &str) -> String {

    let name = artifact_name(version, platform);

    if platform.starts_with("windows-") {

        format!("{name}.exe")

    } else {

        name

    }

}

pub fn hex_digest(bytes: &[u8]) -> String {

    let digest = Sha256::digest(bytes);

    digest.iter().map(|byte| format!("{byte:02x}")).collect()

}

pub struct Updater {

    pub base_url: String,

    pub channel: String,

    http: reqwest::Client,

}

/// What an update run decided, so a caller can report it without inferring it

/// from printed text.

#[derive(Debug, PartialEq, Eq)]

pub enum Outcome {

    AlreadyCurrent {

        version: String,

    },

    Available {

        version: String,

    },

    Replaced {

        from: String,

        to: String,

        path: PathBuf,

    },

}

impl Updater {

    pub fn new(base_url: Option<String>, channel: Option<String>) -> Self {

        let base_url = base_url

            .or_else(|| std::env::var("OPENAGENTS_RELEASES_BASE_URL").ok())

            .unwrap_or_else(|| DEFAULT_BASE_URL.to_string());

        let channel = channel

            .or_else(|| std::env::var("OPENAGENTS_CHANNEL").ok())

            .unwrap_or_else(|| DEFAULT_CHANNEL.to_string());

        Self {

            base_url: base_url.trim_end_matches('/').to_string(),

            channel,

            http: reqwest::Client::new(),

        }

    }

    /// Resolve the channel pointer to the version it currently names.

    pub async fn resolve_channel(&self) -> Result<String, UpdateError> {

        let url = format!("{}/{}", self.base_url, self.channel);

        let response =

            self.http

                .get(&url)

                .send()

                .await

                .map_err(|error| UpdateError::ChannelUnreadable {

                    channel: self.channel.clone(),

                    detail: error.to_string(),

                })?;

        if !response.status().is_success() {

            return Err(UpdateError::ChannelUnreadable {

                channel: self.channel.clone(),

                detail: format!("{} answered {}", url, response.status()),

            });

        }

        let body = response

            .text()

            .await

            .map_err(|error| UpdateError::ChannelUnreadable {

                channel: self.channel.clone(),

                detail: error.to_string(),

            })?;

        let version = body.trim().to_string();

        if !valid_version(&version) {

            return Err(UpdateError::ChannelNotAVersion {

                channel: self.channel.clone(),

                body: version,

            });

        }

        Ok(version)

    }

    /// Download the artifact and prove it is the one the release published.

    ///

    /// The sums file is fetched over its own request rather than alongside the

    /// artifact. A digest that arrived on the same connection as the bytes it

    /// describes proves only that they travelled together.

    pub async fn fetch_verified(

        &self,

        version: &str,

        platform: &str,

    ) -> Result<Vec<u8>, UpdateError> {

        if !valid_version(version) {

            return Err(UpdateError::InvalidVersion(version.to_string()));

        }

        let name = artifact_name(version, platform);

        let url = format!("{}/{}", self.base_url, name);

        let response =

            self.http

                .get(&url)

                .send()

                .await

                .map_err(|error| UpdateError::ArtifactUnavailable {

                    name: name.clone(),

                    detail: error.to_string(),

                })?;

        if !response.status().is_success() {

            return Err(UpdateError::ArtifactUnavailable {

                name: name.clone(),

                detail: format!("{} answered {}", url, response.status()),

            });

        }

        let bytes = response

            .bytes()

            .await

            .map_err(|error| UpdateError::ArtifactUnavailable {

                name: name.clone(),

                detail: error.to_string(),

            })?

            .to_vec();

        let sums_url = format!("{}/SHA256SUMS-{}", self.base_url, version);

        let sums_response = self.http.get(&sums_url).send().await.map_err(|error| {

            UpdateError::SumsUnavailable {

                version: version.to_string(),

                detail: error.to_string(),

            }

        })?;

        if !sums_response.status().is_success() {

            return Err(UpdateError::SumsUnavailable {

                version: version.to_string(),

                detail: format!("{} answered {}", sums_url, sums_response.status()),

            });

        }

        let sums = sums_response

            .text()

            .await

            .map_err(|error| UpdateError::SumsUnavailable {

                version: version.to_string(),

                detail: error.to_string(),

            })?;

        let entry = sums_entry_name(version, platform);

        let expected = digest_for(&sums, &entry).ok_or_else(|| UpdateError::SumsMissingEntry {

            version: version.to_string(),

            name: entry.clone(),

        })?;

        let actual = hex_digest(&bytes);

        if !actual.eq_ignore_ascii_case(&expected) {

            return Err(UpdateError::DigestMismatch {

                name: entry,

                expected,

                actual,

            });

        }

        Ok(bytes)

    }

}

/// The file this process is running from, with symlinks resolved.

///

/// The installer links `~/.openagents/bin/oa` and `~/.openagents/bin/openagents`

/// at a single file under `~/.openagents/downloads`. Replacing the link target

/// is what keeps both names working; replacing a link would leave the other

/// name pointing at the old binary.

pub fn running_binary() -> Result<PathBuf, UpdateError> {

    let path = std::env::current_exe().map_err(|error| UpdateError::ReplaceFailed {

        path: PathBuf::from("<unknown>"),

        detail: format!("could not locate the running binary: {error}"),

    })?;

    Ok(path.canonicalize().unwrap_or(path))

}

/// Write `bytes` over `target` without ever leaving a partial binary there.

///

/// The new file is written beside the target so the final step is a rename

/// within one filesystem, which is atomic: a reader who runs `oa` during an

/// update gets the old binary or the new one and never half of either. On Unix

/// the rename also works while the old binary is executing, because the

/// running process holds the inode rather than the name.

pub fn replace_binary(target: &Path, bytes: &[u8]) -> Result<(), UpdateError> {

    let directory = target.parent().ok_or_else(|| UpdateError::ReplaceFailed {

        path: target.to_path_buf(),

        detail: "the running binary has no parent directory".to_string(),

    })?;

    let file_name = target

        .file_name()

        .map(|name| name.to_string_lossy().to_string())

        .unwrap_or_else(|| "oa".to_string());

    let staged = directory.join(format!(".{}.update.{}", file_name, std::process::id()));

    let fail = |detail: String| UpdateError::ReplaceFailed {

        path: target.to_path_buf(),

        detail,

    };

    std::fs::write(&staged, bytes).map_err(|error| fail(error.to_string()))?;

    #[cfg(unix)]

    {

        use std::os::unix::fs::PermissionsExt;

        std::fs::set_permissions(&staged, std::fs::Permissions::from_mode(0o755))

            .map_err(|error| fail(error.to_string()))?;

    }

    // Windows refuses to rename over a running executable, so the old name is

    // moved aside first. The installer does the same thing with the same

    // `.old` suffix, and Windows will delete it on the next boot or the next

    // update, whichever a reader reaches first.

    #[cfg(windows)]

    let displaced = {

        let displaced = directory.join(format!("{file_name}.old"));

        let _ = std::fs::remove_file(&displaced);

        if target.exists() {

            std::fs::rename(target, &displaced).map_err(|error| fail(error.to_string()))?;

        }

        Some(displaced)

    };

    if let Err(error) = std::fs::rename(&staged, target) {

        let _ = std::fs::remove_file(&staged);

        #[cfg(windows)]

        if let Some(displaced) = displaced {

            let _ = std::fs::rename(&displaced, target);

        }

        return Err(fail(error.to_string()));

    }

    Ok(())

}

/// Run the update.

///

/// `check` stops after resolving the channel: nothing is downloaded and

/// nothing is written, which is what a script that wants to know whether an

/// update exists should call.

pub async fn run(

    channel: Option<String>,

    requested: Option<String>,

    check: bool,

    force: bool,

) -> Result<Outcome, Box<dyn std::error::Error>> {

    let platform = platform().ok_or_else(|| UpdateError::UnsupportedPlatform {

        os: std::env::consts::OS.to_string(),

        arch: std::env::consts::ARCH.to_string(),

    })?;

    let updater = Updater::new(None, channel);

    let current = crate::VERSION;

    let version = match requested {

        Some(version) => {

            if !valid_version(&version) {

                return Err(Box::new(UpdateError::InvalidVersion(version)));

            }

            version

        }

        None => {

            let resolved = updater.resolve_channel().await?;

            println!(

                "Channel '{}' names {} ({} is installed).",

                updater.channel, resolved, current

            );

            resolved

        }

    };

    if version == current && !force {

        println!("Already running {current}. Nothing to do.");

        return Ok(Outcome::AlreadyCurrent {

            version: version.clone(),

        });

    }

    if check {

        println!("Update available: {current} -> {version}");

        return Ok(Outcome::Available { version });

    }

    let target = running_binary()?;

    println!(

        "Downloading {} ({platform})...",

        artifact_name(&version, &platform)

    );

    let bytes = updater.fetch_verified(&version, &platform).await?;

    println!("  Verified sha256 {}.", hex_digest(&bytes));

    replace_binary(&target, &bytes)?;

    println!("Replaced {}.", target.display());

    println!("OpenAgents CLI is now {version}.");

    Ok(Outcome::Replaced {

        from: current.to_string(),

        to: version,

        path: target,

    })

}

//! What `oa update` refuses.

//!

//! The install path and the update path deliver the same bytes to the same

//! machine, so they answer to the same rules: a version the release naming

//! grammar does not admit is not asked for, a sums file that names no entry

//! for the artifact stops the install, a digest that disagrees stops it, and

//! nothing lands at the target path until the bytes have been proven.

use std::collections::HashMap;

use openagents_cli::update::{

    artifact_name, digest_for, hex_digest, platform, replace_binary, sums_entry_name,

    valid_version, UpdateError, Updater,

};

/// A release server that serves exactly what it is given and 404s the rest.

///

/// The refusals under test are about what arrives over the wire, so they are

/// exercised over a real socket rather than against a mocked client that could

/// only prove the mock behaves.

async fn release_server(objects: HashMap<String, Vec<u8>>) -> String {

    let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();

    let base = format!("http://{}", listener.local_addr().unwrap());

    tokio::spawn(async move {

        loop {

            let Ok((mut stream, _peer)) = listener.accept().await else {

                return;

            };

            let objects = objects.clone();

            tokio::spawn(async move {

                use tokio::io::{AsyncReadExt, AsyncWriteExt};

                let mut buffer = [0u8; 2048];

                let Ok(read) = stream.read(&mut buffer).await else {

                    return;

                };

                let request = String::from_utf8_lossy(&buffer[..read]);

                let name = request

                    .split_whitespace()

                    .nth(1)

                    .unwrap_or("/")

                    .trim_start_matches('/')

                    .to_string();

                let response = match objects.get(&name) {

                    Some(body) => {

                        let mut head = format!(

                            "HTTP/1.1 200 OK\r\nContent-Length: {}\r\nConnection: close\r\n\r\n",

                            body.len()

                        )

                        .into_bytes();

                        head.extend_from_slice(body);

                        head

                    }

                    None => {

                        b"HTTP/1.1 404 Not Found\r\nContent-Length: 0\r\nConnection: close\r\n\r\n"

                            .to_vec()

                    }

                };

                let _ = stream.write_all(&response).await;

                let _ = stream.shutdown().await;

            });

        }

    });

    base

}

fn objects(entries: Vec<(&str, &[u8])>) -> HashMap<String, Vec<u8>> {

    entries

        .into_iter()

        .map(|(name, body)| (name.to_string(), body.to_vec()))

        .collect()

}

#[test]

fn the_version_grammar_matches_the_one_the_release_publishes() {

    // ops/release-cli.sh: ^[0-9]+\.[0-9]+\.[0-9]+(-[A-Za-z0-9._]+)?$

    assert!(valid_version("0.1.0"));

    assert!(valid_version("0.1.0-rc.1"));

    assert!(valid_version("10.20.30-alpha_2"));

    assert!(!valid_version(""));

    assert!(!valid_version("0.1"));

    assert!(!valid_version("0.1.0.1"));

    assert!(!valid_version("v0.1.0"));

    assert!(!valid_version("0.1.x"));

    assert!(!valid_version("0.1.0-"));

    assert!(!valid_version("0.1.0-rc-1"));

    assert!(!valid_version("0.1.0-rc 1"));

    // A channel pointer is a URL segment away from a path, and the artifact

    // name is built out of it.

    assert!(!valid_version("../../etc/passwd"));

    assert!(!valid_version("0.1.0/../stable"));

}

#[test]

fn the_windows_sums_entry_carries_an_extension_the_artifact_does_not() {

    // The installer downloads a URL with no extension and then looks up a name

    // with one. The published release reproduces that asymmetry, so the update

    // path has to as well or every Windows update fails on a missing entry.

    assert_eq!(

        artifact_name("0.1.0", "windows-x86_64"),

        "openagents-0.1.0-windows-x86_64"

    );

    assert_eq!(

        sums_entry_name("0.1.0", "windows-x86_64"),

        "openagents-0.1.0-windows-x86_64.exe"

    );

    assert_eq!(

        sums_entry_name("0.1.0", "linux-x86_64-musl"),

        "openagents-0.1.0-linux-x86_64-musl"

    );

}

#[test]

fn a_sums_file_is_read_the_way_the_installer_reads_one() {

    let sums = "\

aaaa  openagents-0.1.0-linux-x86_64

bbbb  openagents-0.1.0-linux-x86_64-musl

cccc *openagents-0.1.0-windows-x86_64.exe

";

    // The glibc and musl entries differ only by suffix, and a prefix match

    // would hand the musl reader the dynamically linked binary.

    assert_eq!(

        digest_for(sums, "openagents-0.1.0-linux-x86_64").as_deref(),

        Some("aaaa")

    );

    assert_eq!(

        digest_for(sums, "openagents-0.1.0-linux-x86_64-musl").as_deref(),

        Some("bbbb")

    );

    // `sha256sum` writes a `*` before the name in binary mode.

    assert_eq!(

        digest_for(sums, "openagents-0.1.0-windows-x86_64.exe").as_deref(),

        Some("cccc")

    );

    assert_eq!(digest_for(sums, "openagents-0.1.0-macos-aarch64"), None);

    assert_eq!(digest_for("", "openagents-0.1.0-linux-x86_64"), None);

}

#[test]

fn the_platform_is_the_one_this_binary_was_built_for() {

    let platform = platform().expect("this target has a published artifact");

    assert!(platform.starts_with(std::env::consts::OS));

    assert!(platform.contains(std::env::consts::ARCH));

    // The libc flavour is settled by the toolchain, not probed at runtime, so

    // it cannot disagree with the binary it names.

    if cfg!(all(target_os = "linux", target_env = "musl")) {

        assert!(platform.ends_with("-musl"));

    } else {

        assert!(!platform.ends_with("-musl"));

    }

}

#[test]

fn the_digest_is_the_one_shasum_would_print() {

    // sha256 of the empty input, which every implementation agrees on.

    assert_eq!(

        hex_digest(b""),

        "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"

    );

}

#[tokio::test]

async fn a_channel_resolves_to_the_version_it_names() {

    let base = release_server(objects(vec![("stable", b"0.1.0-rc.2\n")])).await;

    let updater = Updater::new(Some(base), Some("stable".to_string()));

    assert_eq!(updater.resolve_channel().await.unwrap(), "0.1.0-rc.2");

}

#[tokio::test]

async fn a_channel_that_answers_with_something_else_is_refused() {

    // A bucket that starts serving an error page, an index listing, or a

    // half-written pointer must not become a version the artifact name is

    // built out of.

    let base = release_server(objects(vec![("stable", b"<html>404</html>")])).await;

    let updater = Updater::new(Some(base), Some("stable".to_string()));

    assert!(matches!(

        updater.resolve_channel().await,

        Err(UpdateError::ChannelNotAVersion { .. })

    ));

}

#[tokio::test]

async fn a_verified_artifact_is_returned() {

    let binary = b"the published binary";

    let sums = format!("{}  openagents-0.1.0-linux-x86_64\n", hex_digest(binary));

    let base = release_server(objects(vec![

        ("openagents-0.1.0-linux-x86_64", binary),

        ("SHA256SUMS-0.1.0", sums.as_bytes()),

    ]))

    .await;

    let updater = Updater::new(Some(base), None);

    let bytes = updater

        .fetch_verified("0.1.0", "linux-x86_64")

        .await

        .unwrap();

    assert_eq!(bytes, binary);

}

#[tokio::test]

async fn a_missing_sums_file_stops_the_update() {

    // The artifact is available and would install fine. Without the sums file

    // there is no way to say it is the one that was published, and an update

    // that installs it anyway is a weaker path than the installer's.

    let base = release_server(objects(vec![(

        "openagents-0.1.0-linux-x86_64",

        b"the published binary",

    )]))

    .await;

    let updater = Updater::new(Some(base), None);

    assert!(matches!(

        updater.fetch_verified("0.1.0", "linux-x86_64").await,

        Err(UpdateError::SumsUnavailable { .. })

    ));

}

#[tokio::test]

async fn a_sums_file_naming_no_entry_stops_the_update() {

    let base = release_server(objects(vec![

        ("openagents-0.1.0-linux-x86_64", b"the published binary"),

        (

            "SHA256SUMS-0.1.0",

            b"aaaa  openagents-0.1.0-macos-aarch64\n",

        ),

    ]))

    .await;

    let updater = Updater::new(Some(base), None);

    assert!(matches!(

        updater.fetch_verified("0.1.0", "linux-x86_64").await,

        Err(UpdateError::SumsMissingEntry { .. })

    ));

}

#[tokio::test]

async fn bytes_that_do_not_match_their_digest_stop_the_update() {

    let sums = format!(

        "{}  openagents-0.1.0-linux-x86_64\n",

        hex_digest(b"expected")

    );

    let base = release_server(objects(vec![

        ("openagents-0.1.0-linux-x86_64", b"something else entirely"),

        ("SHA256SUMS-0.1.0", sums.as_bytes()),

    ]))

    .await;

    let updater = Updater::new(Some(base), None);

    assert!(matches!(

        updater.fetch_verified("0.1.0", "linux-x86_64").await,

        Err(UpdateError::DigestMismatch { .. })

    ));

}

#[test]

fn a_replaced_binary_is_never_half_written() {

    let directory = std::env::temp_dir().join(format!("oa-update-{}", std::process::id()));

    std::fs::create_dir_all(&directory).unwrap();

    let target = directory.join("oa");

    std::fs::write(&target, b"old binary").unwrap();

    replace_binary(&target, b"new binary").unwrap();

    assert_eq!(std::fs::read(&target).unwrap(), b"new binary");

    #[cfg(unix)]

    {

        use std::os::unix::fs::PermissionsExt;

        let mode = std::fs::metadata(&target).unwrap().permissions().mode();

        assert_eq!(mode & 0o777, 0o755, "the replacement is not executable");

    }

    // The staging file is gone: a directory left holding a second copy of a

    // 40 MB binary after every update is a leak nobody looks for.

    let leftovers: Vec<_> = std::fs::read_dir(&directory)

        .unwrap()

        .filter_map(Result::ok)

        .map(|entry| entry.file_name().to_string_lossy().to_string())

        .filter(|name| name != "oa")

        .collect();

    assert!(leftovers.is_empty(), "left behind {leftovers:?}");

    std::fs::remove_dir_all(&directory).unwrap();

}

| `<base>/SHA256SUMS-<version>` | One `<sha256>  <name>` line per platform |

The platform strings are `macos-aarch64`, `macos-x86_64`, `linux-x86_64`,

`linux-aarch64`, and `windows-x86_64`.

`linux-x86_64-musl`, `linux-aarch64`, `linux-aarch64-musl`, and

`windows-x86_64`.

Two details of that contract are easy to get wrong, so the script derives both

rather than leaving them to a human:

Three details of that contract are easy to get wrong, so the script derives

each rather than leaving it to a human:

- The artifact URL never carries a file extension, on any platform. The

  installer computes the URL before it branches on Windows and never revisits

  appends that suffix to the name it searches for. The published object and the

  checksum line therefore disagree by design. Changing either one alone breaks

  every Windows install with a checksum mismatch.

- The glibc Linux artifacts carry no libc suffix and the musl ones do. Renaming

  the glibc artifacts to `linux-x86_64-gnu` would be tidier and would strand

  every installer already in circulation, which asks for the unsuffixed name.

## The two Linux builds

A glibc-linked executable does not run on a musl system. The kernel cannot find

the interpreter named in the binary's `PT_INTERP` and reports it as `no such

file or directory` against a path that plainly exists, which is close to the

least legible failure a first install can produce.

So Linux ships twice per architecture. The `-gnu` targets are dynamically

linked and name `/lib64/ld-linux-x86-64.so.2` or `/lib/ld-linux-aarch64.so.1`.

The `-musl` targets are statically linked and name no interpreter at all.

The installer chooses between them by asking whether the glibc loader for the

reader's architecture exists, which is the question that actually decides it

rather than a proxy for it. Distribution detection would need files a minimal

image may not carry, and `ldd` disagrees with itself across implementations:

GNU's prints a version banner to stdout and exits 0, musl's prints `musl libc`

to stderr, and BusyBox's does neither. Loader presence needs no tools at all.

A system that has the loader can run either artifact and takes the dynamically

linked one; a system that does not can only run the static one. That reads

correctly on Alpine, on a BusyBox or distroless image with no `ldd`, on a

Debian host with the `musl` package installed beside glibc, and on NixOS, where

the loader lives in the Nix store and the static build is genuinely the right

answer. Every way the test can be wrong sends the reader to the artifact that

still runs.

`test/openagents_web/install_script_test.exs` in the `openagents.com`

repository extracts `linux_libc` from the served script and runs it against

fixture roots covering each of those cases.

The `file` signatures in the platform table encode the difference — the gnu

rows require `dynamically linked` and the musl rows require `static` — so a

build that silently produced the wrong flavour cannot be published under the

other one's name.