iris/ai-app
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Condense the documentation and thin the server's comments

Browse Source 
The markdown had accumulated a lot that was stale rather than wrong.
PLAN.md still described pi as the llama.cpp harness, a refcounted
LlamaServerManager, and a providers-by-hosts cross-product, all of which
were superseded or never built; it also carried a second copy of the HTTP
table that routes.rs owns. EXPLORER.md and TRANSCRIPT_CACHE.md held
implementation checklists for work that has since landed. AGENTS.md
restated most of PLAN.md's design instead of being the working-notes
layer it says it is. 3225 lines of markdown to 2180, with the stale
sections gone rather than reworded.

On the server, comments explaining what the code already says are out and
the ones recording a constraint, a measurement or an incident are kept but
cut to a few lines each: 5504 comment lines to 4586.

Four doc comments in session/mod.rs, and one each in process.rs and
usage.rs, had drifted onto the item above the one they describe --
functions were reordered without them, so `stop_session`'s doc sat on
`set_session_cwd`, `stat_of`'s on `struct Stat`, and `UsageMonitor`'s on
`type Cached`. Each is back on its own item.

routes.rs's module table also claimed later phases would add `/hosts`,
which setups replaced.

cargo test (127 passed), clippy --all-targets and fmt are clean.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
irisandClaude Opus 5 committed 2026-09-04 15:45:43 -04:00
1 parent e3e02d55f7
commit 79682f03a7
24 files changed
+4572 -6821
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

server/src/usage.rs
+90 -109
View File
@@ -3,36 +3,31 @@
//! Polls `https://api.anthropic.com/api/oauth/usage` with the OAuth access
//! token from Claude Code's local credential store. The endpoint is
//! undocumented and has changed before, so everything here is best-effort:
//! every field is optional, and failure degrades to an "unavailable"
//! snapshot with the reason, never an error that breaks the screen.
//! every field is optional, and failure degrades to an "unavailable" snapshot
//! with the reason, never an error that breaks the screen.
//!
//! Two rules learned from others hitting this endpoint (see PLAN.md's
//! references): send `User-Agent: claude-code/<version>` (without it,
//! requests land in an aggressively rate-limited bucket) and poll no more
//! often than every 180 s. The cache below enforces the latter across any
//! number of phone refreshes; there is no background poll at all -- the
//! screen's fetch is the trigger, so no session activity means no traffic.
//! Two rules learned from others hitting this endpoint: send `User-Agent:
//! claude-code/<version>` (without it, requests land in an aggressively
//! rate-limited bucket) and poll no more often than every 180 s. The cache
//! below enforces the latter across any number of phone refreshes; there is no
//! background poll at all.
//!
//! One [`UsageProvider`] per paid service, so a second service later is a
//! new impl behind the same snapshot shape, not a parallel screen.
//! One [`UsageProvider`] per paid service, so a second service later is a new
//! impl behind the same snapshot shape, not a parallel screen.
//!
//! **Asked of the machine that spends the tokens, not of this one.** A
//! session runs wherever its setup says, so the account being billed is
//! that machine's, and reading this machine's credentials reports on an
//! account that may have run nothing. In the layout this project is aiming
//! at that is not a rounding error: `ai-server` belongs on the host, the
//! host has no `claude` CLI, and the CLI machine is a remote -- so the one
//! set of numbers the screen could show would be the numbers of an account
//! with no sessions. Credentials are therefore read through the session
//! `Transport`, one snapshot per setup that offers Claude.
//! **Asked of the machine that spends the tokens, not of this one.** A session
//! runs wherever its setup says, so the account being billed is that machine's.
//! In the layout this project aims at, `ai-server` is on the host, the host has
//! no `claude` CLI, and the CLI machine is a remote -- so the one set of numbers
//! the screen could show would be an account with no sessions. Credentials are
//! read through the session `Transport`, one snapshot per setup that offers
//! Claude.
//!
//! The token is read *to* the backend and the HTTP call is made from here,
//! rather than running the request on the far machine: it needs no tooling
//! there beyond a shell, and it keeps the one place that knows the wire
//! format in one place. The cost is that a remote machine's token is in
//! this process's memory for the length of a fetch, which is the same
//! trust the backend already has over that machine (it can start processes
//! on it).
//! The token is read *to* the backend and the HTTP call is made from here, so
//! the far machine needs nothing beyond a shell and the wire format stays in
//! one place. The cost is that a remote machine's token is in this process's
//! memory for the length of a fetch, which is the same trust the backend
//! already has over that machine.
use std::collections::HashMap;
use std::sync::Mutex;
@@ -54,15 +49,13 @@ const USER_AGENT: &str = "claude-code/2.1.237";
#[serde(rename_all = "camelCase")]
pub struct UsageWindow {
/// The API's own word for which window this is -- `session` for the
/// five-hour one, `weekly_all`, `weekly_scoped`, or whatever new kind
/// it starts sending.
/// five-hour one, `weekly_all`, `weekly_scoped`, or whatever new kind it
/// starts sending.
///
/// Carried beside the label because a caller that wants one
/// particular window has to be able to ask for it without matching on
/// display text: the label is written for a person, is translated the
/// moment anybody translates this app, and would silently select
/// nothing the day it changes. The session screen's bar picks
/// `session` by this field.
/// Carried beside the label because a caller that wants one particular
/// window has to ask for it without matching on display text: the label is
/// written for a person and would silently select nothing the day it
/// changes.
pub kind: String,
pub label: String,
/// 0-100.
@@ -77,13 +70,11 @@ pub struct UsageWindow {
/// What came back when a machine was asked about its limits.
///
/// Four answers rather than a flag and a message, because the screen has to
/// treat them differently and a reader has to. "Nobody is logged in here"
/// is a machine working exactly as configured -- somebody chose not to put
/// an account on it -- while "I could not reach it" is a fault worth
/// chasing, and "the endpoint refused me" is a third thing that says
/// nothing about the machine at all. Collapsing them into one `error`
/// string made the first look like the last, so a perfectly healthy setup
/// read as broken.
/// treat them differently. "Nobody is logged in here" is a machine working
/// exactly as configured, while "I could not reach it" is a fault worth
/// chasing, and "the endpoint refused me" says nothing about the machine at
/// all. Collapsing them into one `error` string made the first look like the
/// last, so a perfectly healthy setup read as broken.
#[derive(Debug, Clone, Serialize, PartialEq)]
#[serde(tag = "state", rename_all = "camelCase")]
pub enum UsageState {
@@ -102,11 +93,11 @@ pub enum UsageState {
#[serde(rename_all = "camelCase")]
pub struct UsageSnapshot {
pub provider: String,
/// Which machine these are the numbers for. The point of the whole
/// module: they belong to an account on a particular box.
/// Which machine these are the numbers for. The point of the whole module:
/// they belong to an account on a particular box.
pub setup: String,
/// That machine's current label, resolved when the snapshot is built,
/// so renaming a setup renames it here too.
/// That machine's current label, resolved when the snapshot is built, so
/// renaming a setup renames it here too.
pub setup_name: String,
#[serde(flatten)]
pub state: UsageState,
@@ -122,9 +113,9 @@ pub trait UsageProvider: Send + Sync {
fn fetch(&self) -> UsageSnapshot;
}
/// Reads the numbers behind Claude Code's `/usage` from one machine, using
/// the credentials that machine stores -- nothing to configure, and it
/// reports on exactly the account whose CLI runs the sessions there.
/// Reads the numbers behind Claude Code's `/usage` from one machine, using the
/// credentials that machine stores -- nothing to configure, and it reports on
/// exactly the account whose CLI runs the sessions there.
pub struct ClaudeUsage {
pub setup: String,
pub setup_name: String,
@@ -132,9 +123,9 @@ pub struct ClaudeUsage {
pub transport: Transport,
}
/// Where Claude Code keeps its credentials, as a shell word rather than a
/// path: `$HOME` is expanded by the shell on the machine being asked,
/// which is the only place that knows what it is.
/// Where Claude Code keeps its credentials, as a shell word rather than a path:
/// `$HOME` is expanded by the shell on the machine being asked, which is the
/// only place that knows what it is.
const CREDENTIALS: &str = "$HOME/.claude/.credentials.json";
impl ClaudeUsage {
@@ -149,12 +140,9 @@ impl ClaudeUsage {
}
}
/// The machine's stored OAuth token, or which of the two ways of not
/// having one this is.
///
/// Read through `sh -c` so `$HOME` resolves on the far machine; a path
/// built here would be this machine's home directory, which over ssh
/// is somebody else's.
/// The machine's stored OAuth token, or which of the two ways of not having
/// one this is. Read through `sh -c` so `$HOME` resolves on the far machine;
/// a path built here would be this machine's home directory.
fn access_token(&self) -> Result<String, UsageState> {
let launch = Launch::new(
"sh",
@@ -174,8 +162,8 @@ impl ClaudeUsage {
.as_str()
.map(String::from)
})
// A file that exists but carries no token is the same situation
// as no file: nobody has logged in here yet.
// A file that exists but carries no token is the same situation as
// no file: nobody has logged in here yet.
.ok_or(UsageState::NotLoggedIn)
}
}
@@ -225,19 +213,17 @@ impl UsageProvider for ClaudeUsage {
/// Which kind of "no credentials" a failed read was.
///
/// The distinction is the point of having both states. `cat` failing
/// because the file is not there is a machine nobody has logged in on --
/// a decision somebody made, with nothing to fix. Anything else is a
/// machine this server could not ask, which is a fault and reads as one.
/// The distinction is the point of having both states. `cat` failing because
/// the file is not there is a machine nobody has logged in on -- a decision
/// somebody made, with nothing to fix. Anything else is a machine this server
/// could not ask, which is a fault and reads as one.
///
/// Matched on the shell's own words rather than an exit status because
/// there is only one: `cat` exits 1 for a missing file and ssh exits 255
/// for a connection it could not make, but the message is what survives
/// being wrapped in `sh -c` and passed back through ssh.
/// Matched on the shell's own words rather than an exit status because there is
/// only one that survives being wrapped in `sh -c` and passed back through ssh.
fn why_no_credentials(detail: &str) -> UsageState {
// "No such file or directory" is GNU and BSD coreutils; busybox says
// "can't open". Anything unrecognised is treated as unreachable,
// which is the answer that gets looked at rather than ignored.
// "No such file or directory" is GNU and BSD coreutils; busybox says "can't
// open". Anything unrecognised is treated as unreachable, which is the
// answer that gets looked at rather than ignored.
let missing = ["No such file", "no such file", "can't open", "cannot open"];
if missing.iter().any(|phrase| detail.contains(phrase)) {
UsageState::NotLoggedIn
@@ -248,10 +234,9 @@ fn why_no_credentials(detail: &str) -> UsageState {
}
}
/// Pulls the `limits` array apart, defensively: entries with no percent
/// are skipped, unknown kinds keep their raw name as the label rather
/// than being dropped -- a new window appearing should show up, not
/// vanish.
/// Pulls the `limits` array apart, defensively: entries with no percent are
/// skipped, and unknown kinds keep their raw name as the label rather than
/// being dropped -- a new window appearing should show up, not vanish.
fn parse_windows(body: &Value) -> Vec<UsageWindow> {
let Some(limits) = body.get("limits").and_then(Value::as_array) else {
return Vec::new();
@@ -295,10 +280,10 @@ fn parse_windows(body: &Value) -> Vec<UsageWindow> {
/// Which paid services a machine can be asked about.
///
/// Derived from what the setup says it can run, so a machine with no
/// Claude provider is not asked about Claude limits -- it has none, and a
/// row saying so would be a fact about nothing. A second service later
/// adds a branch here and an impl beside [`ClaudeUsage`], not a screen.
/// Derived from what the setup says it can run, so a machine with no Claude
/// provider is not asked about Claude limits -- it has none, and a row saying
/// so would be a fact about nothing. A second service later adds a branch here
/// and an impl beside [`ClaudeUsage`], not a screen.
fn providers_for(setup: &SetupConfig) -> Vec<Box<dyn UsageProvider>> {
let mut found: Vec<Box<dyn UsageProvider>> = Vec::new();
if setup
@@ -315,19 +300,17 @@ fn providers_for(setup: &SetupConfig) -> Vec<Box<dyn UsageProvider>> {
found
}
/// The cache in front of whatever machines exist: at most one real fetch
/// per machine per service per [`MIN_POLL_INTERVAL`], no matter how often
/// the phone asks.
///
/// One machine's numbers for one service, and when they were fetched.
///
/// Keyed by the machine and the service rather than by position: the set
/// is no longer fixed at startup -- setups are added, renamed and removed
/// from the phone -- and a positional cache would hand one machine's
/// numbers to another the moment the list shifted.
/// Keyed by the machine and the service rather than by position: the set is not
/// fixed at startup -- setups are added, renamed and removed from the phone --
/// and a positional cache would hand one machine's numbers to another the
/// moment the list shifted.
type Cached = HashMap<(String, &'static str), (Instant, UsageSnapshot)>;
#[derive(Default)]
/// The cache in front of whatever machines exist: at most one real fetch per
/// machine per service per [`MIN_POLL_INTERVAL`], however often the phone asks.
pub struct UsageMonitor {
cache: Mutex<Cached>,
}
@@ -337,12 +320,12 @@ impl UsageMonitor {
Self::default()
}
/// One snapshot per machine that offers a paid service, in the order
/// the machines are configured.
/// One snapshot per machine that offers a paid service, in the order the
/// machines are configured.
///
/// Blocking -- call via `spawn_blocking`. Takes the setups rather than
/// holding the manager, so this module stays below the session layer
/// rather than reaching up into it.
/// holding the manager, so this module stays below the session layer rather
/// than reaching up into it.
pub fn snapshots(&self, setups: &[SetupConfig]) -> Vec<UsageSnapshot> {
let mut fresh = Vec::new();
for setup in setups {
@@ -351,19 +334,17 @@ impl UsageMonitor {
if let Some((fetched, snapshot)) = self.cache.lock().unwrap().get(&key)
&& fetched.elapsed() < MIN_POLL_INTERVAL
{
// Cached numbers, but the machine's *name* is read
// fresh: a rename should show immediately rather than
// waiting out the poll interval it has nothing to do
// with.
// Cached numbers, but the machine's *name* is read fresh: a
// rename should show immediately rather than waiting out a
// poll interval it has nothing to do with.
let mut snapshot = snapshot.clone();
snapshot.setup_name = setup.name.clone();
fresh.push(snapshot);
continue;
}
// Fetched without the lock held: this makes a network call
// per machine, and holding the cache across them would
// serialise every phone asking for the screen behind the
// slowest ssh connection.
// Fetched without the lock held: this makes a network call per
// machine, and holding the cache across them would serialise
// every phone asking for the screen behind the slowest ssh.
let snapshot = provider.fetch();
self.cache
.lock()
@@ -412,8 +393,8 @@ mod tests {
assert_eq!(windows[3].resets_at, None);
}
/// A setup naming a machine that cannot be dialled, so nothing here
/// touches the network beyond ssh failing to resolve it.
/// A setup naming a machine that cannot be dialled, so nothing here touches
/// the network beyond ssh failing to resolve it.
fn unreachable_setup() -> SetupConfig {
SetupConfig {
id: "far".to_string(),
@@ -442,9 +423,9 @@ mod tests {
transport: Transport::for_setup(&unreachable_setup()),
};
let snapshot = provider.fetch();
// The distinction the old single `error` string could not make:
// this machine was never reached, which is not the same as a
// machine that answered and has nobody logged in.
// The distinction the old single `error` string could not make: this
// machine was never reached, which is not the same as a machine that
// answered and has nobody logged in.
assert!(
matches!(snapshot.state, UsageState::Unreachable { .. }),
"{:?}",
@@ -457,8 +438,8 @@ mod tests {
#[test]
fn a_missing_credential_file_is_a_choice_and_anything_else_is_a_fault() {
// What a real shell says when nobody has logged in on that
// machine. Nothing to fix, so it must not read as an error.
// What a real shell says when nobody has logged in on that machine.
// Nothing to fix, so it must not read as an error.
assert_eq!(
why_no_credentials("cat: /home/x/.claude/.credentials.json: No such file or directory"),
UsageState::NotLoggedIn
@@ -468,16 +449,16 @@ mod tests {
UsageState::NotLoggedIn
);
// What ssh says when the machine is not there. Worth chasing, and
// the detail is carried so somebody can.
// What ssh says when the machine is not there. Worth chasing, and the
// detail is carried so somebody can.
let refused = why_no_credentials("ssh: connect to host vm port 22: Connection refused");
assert!(
matches!(&refused, UsageState::Unreachable { detail } if detail.contains("refused")),
"{refused:?}"
);
// Anything unrecognised errs towards the state that gets looked
// at, rather than silently claiming nobody is logged in.
// Anything unrecognised errs towards the state that gets looked at,
// rather than silently claiming nobody is logged in.
assert!(matches!(
why_no_credentials("something nobody has seen before"),
UsageState::Unreachable { .. }