//! The account's inference money, as the server reports it.

//!

//! ## Why this is read rather than counted

//!

//! Credit is the account's, not this session's: the server prices the call,

//! the account holds the balance, and a second terminal signed in to the same

//! account spends the same money. A client that subtracted what it saw would

//! show one session's spend as an account's, and would show a full balance to

//! the terminal that opened second. So the figure comes from

//! `GET /api/v1/credit` and nothing here computes one.

//!

//! ## Nothing is reported that was not received

//!

//! [`CreditField`] has three states because there are three things that can be

//! true, and a status bar that collapsed them would be lying in one of them:

//!

//! - **Nothing read yet.** The field is absent from the row. Not `$0.00`, and

//!   not a hopeful blank that looks like a balance of nothing.

//! - **Read, and the answer did not come back.** The row says the balance is

//!   unavailable. It does **not** keep showing the last figure it saw: a stale

//!   number beside a live session is indistinguishable from a current one.

//! - **Read, and the server answered.** Now there is a figure — with one

//!   exception below.

//!

//! ## Why an answer is sometimes still not a figure

//!

//! `remaining_microusd` is a ceiling, not a balance. A model this deployment

//! declares no rates for records no cost, so its calls draw nothing down and

//! the remainder does not move — and the lane the coder runs on is one of them

//! today. A status bar that printed the remainder anyway would sit at `$20.00`

//! through an afternoon of real work, and a figure a reader can watch not move

//! is worse than no figure: it does not read as "unknown", it reads as "you

//! have spent nothing". A 12-task benchmark run on 2026-08-26 returned 0 of 12

//! calls priced, so this is the measured state of the lane rather than a

//! precaution.

//!

//! So a figure is printed only while the server says the spend behind it is

//! complete. The moment an unpriced call is metered, the row says how many

//! calls the server could not price and prints no number. That is the same

//! rule the server's own `Credit.balance/1` documents (METER-001).

//!

//! The two no-figure states are worded differently on purpose. "Unavailable"

//! is *we did not hear back*; "N calls unpriced" is *we heard back and the

//! deployment cannot price part of this*. They are different failures, they

//! are fixed by different people, and a reader has to be able to tell them

//! apart.

use std::time::Duration;

use serde::Deserialize;

/// How long the status bar waits for a balance before giving up on this

/// refresh. Short on purpose: a slow deployment must not hold a frame, and

/// giving up says so rather than showing the previous answer.

const TIMEOUT: Duration = Duration::from_secs(5);

/// What `GET /api/v1/credit` answers with.

#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]

pub struct Credit {

    /// What this account was granted, in microUSD. Per account, not per

    /// deployment: an account created before the grant changed holds what it

    /// was granted.

    pub allowance_microusd: i64,

    /// What the account's grants have metered, in microUSD. A floor while

    /// `complete` is false.

    pub spent_microusd: i64,

    /// `allowance_microusd - spent_microusd`, never negative. A ceiling on

    /// what is left rather than a balance while `complete` is false.

    pub remaining_microusd: i64,

    /// How many of the account's metered calls landed on a model with no

    /// declared rates, and so drew nothing down.

    pub unpriced_calls: u64,

    /// Whether every call the account made was priced. False is the server

    /// saying its own figures are incomplete.

    pub complete: bool,

}

/// What the status bar knows about the balance right now.

#[derive(Debug, Clone, Default, PartialEq, Eq)]

pub enum CreditField {

    /// No read has answered yet, so the row says nothing about credit.

    #[default]

    Unread,

    /// A read was made and did not come back with an answer.

    Unavailable,

    /// The server answered, and this is what it said.

    Known(Credit),

}

#[derive(Debug, Deserialize)]

struct Envelope {

    credit: Credit,

}

impl CreditField {

    /// Record the outcome of one read. `None` is a read that did not answer.

    ///

    /// A failed read replaces a previous answer rather than leaving it up.

    /// That is the whole reason this takes the outcome instead of only the

    /// successes.

    pub fn record(&mut self, outcome: Option<Credit>) {

        *self = match outcome {

            Some(credit) => CreditField::Known(credit),

            None => CreditField::Unavailable,

        };

    }

    /// What the status bar prints for the balance, or nothing.

    ///

    /// Four answers for four states, and no two of them can be mistaken for

    /// each other: nothing at all before a read, `credit: unavailable` when a

    /// read failed, `credit: N calls unpriced` when the server's own spend is

    /// incomplete, and a dollar figure only when it is not.

    pub fn status(&self) -> String {

        match self {

            CreditField::Unread => String::new(),

            CreditField::Unavailable => "credit: unavailable".to_string(),

            CreditField::Known(credit) if credit.complete => {

                format!("{} left", dollars(credit.remaining_microusd))

            }

            CreditField::Known(credit) => {

                let calls = credit.unpriced_calls;

                let plural = if calls == 1 { "call" } else { "calls" };

                format!("credit: {calls} unpriced {plural}")

            }

        }

    }

}

/// microUSD as the dollars a reader recognises, rounded to the cent.

///

/// Rounded down, so the figure is never larger than what the account holds.

fn dollars(microusd: i64) -> String {

    let cents = microusd.max(0) / 10_000;

    format!("${}.{:02}", cents / 100, cents % 100)

}

/// Read the account's credit from the deployment this session is talking to.

///

/// `None` for every failure — no network, a refusal, a body that did not

/// parse. The caller records that as [`CreditField::Unavailable`] rather than

/// keeping what it last knew, because a figure that has stopped being refreshed

/// looks exactly like one that is current.

pub async fn fetch(api_base: &str, token: &str) -> Option<Credit> {

    let client = reqwest::Client::builder().timeout(TIMEOUT).build().ok()?;

    let url = format!("{}/credit", api_base.trim_end_matches('/'));

    let response = client.get(url).bearer_auth(token).send().await.ok()?;

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

        return None;

    }

    let envelope: Envelope = response.json().await.ok()?;

    Some(envelope.credit)

}

#[cfg(test)]

mod tests {

    use super::*;

    /// The exact body `OpenAgentsWeb.CreditController` writes for an account

    /// that has spent $1.60 of a $20 grant on priced lanes.

    const PRICED: &str = r#"{"credit":{"allowance_microusd":20000000,

        "spent_microusd":1600000,"remaining_microusd":18400000,

        "unpriced_calls":0,"complete":true}}"#;

    /// The same account after turns on the coder's own unpriced lane: the

    /// remainder did not move, and the server says why.

    const UNPRICED: &str = r#"{"credit":{"allowance_microusd":20000000,

        "spent_microusd":0,"remaining_microusd":20000000,

        "unpriced_calls":3,"complete":false}}"#;

    fn parse(body: &str) -> Credit {

        serde_json::from_str::<Envelope>(body)

            .expect("the controller's body")

            .credit

    }

    fn known(body: &str) -> CreditField {

        CreditField::Known(parse(body))

    }

    #[test]

    fn nothing_is_said_before_anything_is_read() {

        assert_eq!(CreditField::default().status(), "");

    }

    #[test]

    fn a_complete_balance_prints_the_figure() {

        assert_eq!(known(PRICED).status(), "$18.40 left");

    }

    #[test]

    fn an_incomplete_balance_prints_no_figure_at_all() {

        let status = known(UNPRICED).status();

        assert_eq!(status, "credit: 3 unpriced calls");

        // The property, stated rather than implied: the remainder is $20.00

        // and this is the account that spent real tokens on an unpriced lane,

        // so the one thing the line must not contain is that figure.

        assert!(

            !status.contains("20.00") && !status.contains('$'),

            "an unpriced balance must not print a dollar figure: {status:?}"

        );

    }

    #[test]

    fn one_unpriced_call_reads_as_one_call() {

        let CreditField::Known(mut credit) = known(UNPRICED) else {

            unreachable!("known/1 returns a known field")

        };

        credit.unpriced_calls = 1;

        assert_eq!(

            CreditField::Known(credit).status(),

            "credit: 1 unpriced call"

        );

    }

    #[test]

    fn a_failed_read_says_so_rather_than_zero() {

        let mut field = CreditField::default();

        field.record(None);

        let status = field.status();

        assert_eq!(status, "credit: unavailable");

        assert!(

            !status.contains('$') && !status.contains('0'),

            "an unavailable balance must not print a figure: {status:?}"

        );

    }

    /// The failure the whole three-state shape exists for.

    #[test]

    fn a_failed_read_replaces_the_previous_figure_rather_than_leaving_it_up() {

        let mut field = CreditField::default();

        field.record(Some(parse(PRICED)));

        assert_eq!(field.status(), "$18.40 left");

        field.record(None);

        assert_eq!(field.status(), "credit: unavailable");

    }

    /// The two no-figure states are distinguishable, which is the point of

    /// having two of them.

    #[test]

    fn an_unavailable_read_and_an_unpriced_lane_do_not_read_alike() {

        assert_ne!(CreditField::Unavailable.status(), known(UNPRICED).status());

    }

    #[test]

    fn a_fresh_account_prints_its_whole_grant() {

        let credit = Credit {

            allowance_microusd: 20_000_000,

            spent_microusd: 0,

            remaining_microusd: 20_000_000,

            unpriced_calls: 0,

            complete: true,

        };

        assert_eq!(CreditField::Known(credit).status(), "$20.00 left");

    }

    #[test]

    fn an_account_granted_before_the_figure_changed_prints_what_it_holds() {

        let credit = Credit {

            allowance_microusd: 100_000_000,

            spent_microusd: 0,

            remaining_microusd: 100_000_000,

            unpriced_calls: 0,

            complete: true,

        };

        assert_eq!(CreditField::Known(credit).status(), "$100.00 left");

    }

    #[test]

    fn an_exhausted_account_prints_zero_rather_than_nothing() {

        let credit = Credit {

            allowance_microusd: 20_000_000,

            spent_microusd: 20_000_000,

            remaining_microusd: 0,

            unpriced_calls: 0,

            complete: true,

        };

        assert_eq!(CreditField::Known(credit).status(), "$0.00 left");

    }

    #[test]

    fn cents_are_rounded_down_rather_than_up() {

        // $0.019999 is not two cents to an account that has to pay for it.

        assert_eq!(dollars(19_999), "$0.01");

        assert_eq!(dollars(-1), "$0.00");

    }

}

    let mut terminal = Terminal::new(backend)?;

    terminal.show_cursor()?;

    // What the account holds before this session has spent anything, so the

    // bottom row carries a balance from the first frame rather than only after

    // a turn.

    if session.is_some() {

        refresh_credit(&tx);

    }

    loop {

        while let Ok(control) = rx.try_recv() {

            // A turn that has stopped, either way, is the moment the server's

            // figure can have moved. Read it again rather than adjusting the

            // one on screen: this terminal is not the only thing spending.

            let settled = matches!(control, Control::Done | Control::Failed(_));

            apply(&mut ui, control);

            if settled {

                refresh_credit(&tx);

            }

        }

        terminal.draw(|f| {

                                    crate::runtime::api_base()

                                ),

                            ));

                            // The account is only now known, so this is the

                            // first read that can answer.

                            refresh_credit(&tx);

                        }

                        Err(error) => {

                            ui.entries.push(Entry::new(

    Ok(())

}

/// Ask the deployment what the account has left, off the frame loop.

///

/// Spawned rather than awaited, because a slow deployment must not hold a

/// frame: the answer arrives as a [`Control`] like everything else. The

/// outcome is sent either way, including when there is no credential to ask

/// with — the bottom row has to stop showing a figure it can no longer

/// confirm, and `None` is what tells it to.

fn refresh_credit(tx: &Sender<Control>) {

    let token = crate::runtime::user_token();

    let base = crate::runtime::api_base();

    let tx = tx.clone();

    tokio::spawn(async move {

        let outcome = match token {

            Some(token) => crate::credit::fetch(&base, &token).await,

            None => None,

        };

        let _ = tx.send(Control::Credit(outcome));

    });

}

/// Check that a token is accepted by the deployment without calling GitHub.

/// `GET /api/v1/models` is a light, non-GitHub endpoint that still requires a

/// valid bearer token, so a 200 here means the token is good to spend.

                ui.add_usage(usage);

            }

        }

        // Replaced rather than accumulated: it is the account's balance as of

        // that read, not a delta this session can add up. A read that found

        // nothing replaces the figure too — see `crate::credit`.

        Control::Credit(outcome) => ui.credit.record(outcome),

        Control::Notice(text) => {

            if !text.trim().is_empty() {

                ui.entries.push(Entry::new(Role::Notice, text));

pub mod acp_harness;

pub mod acp_tool;

pub mod commands;

pub mod credit;

pub mod export;

pub mod interactive;

pub mod markdown;

    Model(String),

    /// What the turn spent, as the server reported it.

    Usage(TurnUsage),

    /// What one read of `GET /api/v1/credit` found, and `None` when it found

    /// nothing. Read rather than subtracted from `Usage`: spend is the

    /// server's, and this session is not the only thing spending it. The

    /// failure travels too, because the frame has to stop showing the previous

    /// answer rather than leave it up.

    Credit(Option<crate::credit::Credit>),

    /// Something worth saying that is not the model talking.

    Notice(String),

    /// What one of the session's own commands printed. Markdown, rendered the

    pub loading: bool,

    pub tick: u64,

    pub total_usage: TurnUsage,

    /// What the last read of the account's credit found, or that it found

    /// nothing.

    ///

    /// Nothing here derives it from [`Self::total_usage`]: that total is this

    /// session's, and the credit is the account's. See [`crate::credit`] for

    /// why a failed read clears this rather than leaving the last figure up.

    pub credit: crate::credit::CreditField,

    pub agents: Vec<crate::acp::Agent>,

    /// Hyperlinks on the last rendered frame, in absolute screen coordinates.

    ///

            loading: false,

            tick: 0,

            total_usage: TurnUsage::default(),

            credit: crate::credit::CreditField::Unread,

            agents: Vec::new(),

            links: Vec::new(),

        }

        self.total_usage.add(usage);

    }

    /// The bottom row, as a `·`-joined list of the fields that have something

    /// to say.

    ///

    /// The credit and the tokens are facts about two different things, which

    /// is why they are separate fields rather than one combined figure: the

    /// tokens are this terminal's turn totals, and the credit is the account's,

    /// read from the server, and possibly moved by another terminal since. A

    /// field with nothing to report contributes nothing, so the row never

    /// carries a placeholder that could be read as a value.

    pub fn status_line(credit: &crate::credit::CreditField, usage: &TurnUsage) -> String {

        let fields = [

            credit.status(),

            format!(

                "{} prompt + {} completion = {} tokens",

                usage.prompt_tokens, usage.completion_tokens, usage.total_tokens

            ),

        ];

        fields

            .iter()

            .filter(|field| !field.is_empty())

            .cloned()

            .collect::<Vec<_>>()

            .join(" · ")

    }

    pub fn render(&mut self, frame: &mut Frame, area: Rect) {

        self.tick = self.tick.wrapping_add(1);

        let style = Style::default().fg(TEXT_COLOR).bg(BACKGROUND_COLOR);

        frame.set_cursor_position(Position::new(cursor_x, cursor_y));

        let status_area = main[2];

        let status = format!(

            "{} prompt + {} completion = {} tokens",

            self.total_usage.prompt_tokens,

            self.total_usage.completion_tokens,

            self.total_usage.total_tokens

        );

        let status = Self::status_line(&self.credit, &self.total_usage);

        let status_widget = Paragraph::new(status)

            .style(style)

            .alignment(ratatui::layout::Alignment::Right);

//! `run_tui` opens a session only when a stored credential validates against

//! `GET {origin}/api/v1/models`. The harness therefore points

//! `OPENAGENTS_API_URL` at a stub HTTP server it starts on loopback, which

//! answers that one route with `200` and refuses everything else. So the

//! session is real, the frame is real, no provider credential is spent, and

//! nothing leaves the machine. A turn is never completed on purpose: what is

//! asserted is that Enter *starts* one, which is the part the composer owns.

//! answers that route and `GET {origin}/api/v1/credit` — the one the status

//! bar reads its balance from — with `200`, and refuses everything else. So

//! the session is real, the frame is real, no provider credential is spent,

//! and nothing leaves the machine. A turn is never completed on purpose: what

//! is asserted is that Enter *starts* one, which is the part the composer owns.

#[cfg(not(unix))]

#[test]

    // ─────────────────────────────────────────────────── the stub deployment

    /// A loopback HTTP server that answers exactly one route.

    /// A loopback HTTP server that answers exactly two routes.

    ///

    /// `GET …/api/v1/models` is what `validate_token` calls to decide whether

    /// a session may open, and it is the only thing this harness wants a

    /// deployment for. Everything else is refused with `503` and a body that

    /// a session may open. `GET …/api/v1/credit` is what the status bar reads

    /// its balance from, and it answers the exact body

    /// `OpenAgentsWeb.CreditController` writes — so the figure on the bottom

    /// row is one this binary parsed out of an HTTP response rather than one a

    /// test handed it. Everything else is refused with `503` and a body that

    /// says who refused it, so a request this harness did not intend is

    /// legible rather than silently satisfied.

    struct Stub {

        origin: String,

    }

    /// A $20 account that has spent $1.60 on priced lanes, every call priced.

    const STUB_CREDIT: &str = concat!(

        r#"{"credit":{"allowance_microusd":20000000,"spent_microusd":1600000,"#,

        r#""remaining_microusd":18400000,"unpriced_calls":0,"complete":true}}"#

    );

    /// The same account after three turns on a lane this deployment has no

    /// rates for: nothing was drawn down, and the server says its own spend

    /// figure is incomplete.

    const STUB_CREDIT_UNPRICED: &str = concat!(

        r#"{"credit":{"allowance_microusd":20000000,"spent_microusd":0,"#,

        r#""remaining_microusd":20000000,"unpriced_calls":3,"complete":false}}"#

    );

    impl Stub {

        fn start() -> Self {

            Self::start_with_credit(STUB_CREDIT)

        }

        fn start_with_credit(credit: &'static str) -> Self {

            let listener = TcpListener::bind("127.0.0.1:0").expect("bind loopback stub");

            let port = listener.local_addr().expect("stub address").port();

            std::thread::spawn(move || {

                        }

                    }

                    let head = String::from_utf8_lossy(&request).to_string();

                    let response = if head.starts_with("GET ") && head.contains("/api/v1/models") {

                        let body = r#"{"data":[]}"#;

                    let served = if head.starts_with("GET ") && head.contains("/api/v1/models") {

                        Some(r#"{"data":[]}"#)

                    } else if head.starts_with("GET ") && head.contains("/api/v1/credit") {

                        Some(credit)

                    } else {

                        None

                    };

                    let response = if let Some(body) = served {

                        format!(

                            "HTTP/1.1 200 OK\r\nContent-Type: application/json\r\n\

                             Content-Length: {}\r\nConnection: close\r\n\r\n{body}",

                            body.len()

                        )

                    } else {

                        let body = "the coder-lite PTY harness stub serves /api/v1/models only";

                        let body =

                            "the coder-lite PTY harness stub serves /api/v1/models and /credit";

                        format!(

                            "HTTP/1.1 503 Service Unavailable\r\nContent-Type: text/plain\r\n\

                             Content-Length: {}\r\nConnection: close\r\n\r\n{body}",

            Self::start_sized(ROWS, COLS)

        }

        /// A session whose deployment answers `GET /api/v1/credit` with one

        /// named body, so a test can drive the status bar's states from the

        /// wire rather than from the renderer.

        fn start_with_credit(credit: &'static str) -> Self {

            Self::start_full(ROWS, COLS, credit)

        }

        fn start_sized(rows: u16, cols: u16) -> Self {

            let stub = Stub::start();

            Self::start_full(rows, cols, STUB_CREDIT)

        }

        fn start_full(rows: u16, cols: u16, credit: &'static str) -> Self {

            let stub = Stub::start_with_credit(credit);

            let home = scratch_dir();

            let workdir = home.join("workdir");

            std::fs::create_dir_all(&workdir).expect("create the scratch working directory");

            |frame| {

                frame

                    .transcript()

                    .contains("the coder-lite PTY harness stub serves /api/v1/models only")

                    .contains("the coder-lite PTY harness stub serves /api/v1/models and /credit")

            },

        );

    }

        );

    }

    /// The balance on the bottom row is the deployment's, not this session's.

    ///

    /// The stub answers `GET /api/v1/credit` with the body the server writes

    /// for a $20 account that has spent $1.60, so what this asserts is a figure

    /// that travelled over HTTP, through `serde`, into the frame — not one a

    /// test handed the renderer. Nothing in the session has spent a token, so a

    /// build that derived the balance from its own usage counter would show the

    /// whole $20.00 here and go red.

    #[test]

    fn the_status_bar_carries_the_balance_the_server_reported() {

        let tui = Tui::start();

        let frame = tui.wait_for("the status bar to carry a balance", FIRST_FRAME, |frame| {

            frame.status_bar().contains("$18.40")

        });

        let status = frame.status_bar();

        assert!(

            status.contains("$18.40 left"),

            "the bottom row should carry the remaining balance, and held {:?}.\n{}",

            status,

            frame.dump()

        );

        assert!(

            status.contains("tokens"),

            "the balance goes beside the token counts, not instead of them: {:?}.\n{}",

            status,

            frame.dump()

        );

        // $20.00 is the allowance, and printing it would be reporting a grant

        // as a balance.

        assert!(

            !status.contains("$20.00"),

            "the bottom row printed the allowance rather than the remainder: {:?}.\n{}",

            status,

            frame.dump()

        );

    }

    /// The other display state, and the one the coder's own lane is in today.

    ///

    /// The deployment answers with a remainder of $20.00 that three unpriced

    /// calls did not move, and says so. The bottom row must report the calls it

    /// cannot see rather than the figure it was handed: a status bar showing

    /// `$20.00 left` beside a session that has been working all afternoon is

    /// the exact failure `Credit.unpriced_calls/1` exists to prevent.

    #[test]

    fn an_unpriced_lane_reports_what_it_cannot_see_rather_than_a_figure() {

        let tui = Tui::start_with_credit(STUB_CREDIT_UNPRICED);

        let frame = tui.wait_for(

            "the status bar to report the unpriced calls",

            FIRST_FRAME,

            |frame| frame.status_bar().contains("unpriced"),

        );

        let status = frame.status_bar();

        assert!(

            status.contains("credit: 3 unpriced calls"),

            "the bottom row should name the calls the server could not price, \

             and held {:?}.\n{}",

            status,

            frame.dump()

        );

        assert!(

            !status.contains('$'),

            "an unpriced balance must print no dollar figure at all: {:?}.\n{}",

            status,

            frame.dump()

        );

    }

    /// Leaving hands the terminal back: raw mode off, alternate screen left.

    ///

    /// The termios check is read from the pty master after the child is gone,