thirdshift 0.32.0

Turn a GitHub issue into a ready-for-review pull request, unattended
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
//! Plan usage: how much of each subscription Harness's allowance is used,
//! saved per machine. Running sessions update it passively from structured
//! wire frames; `thirdshift plan-usage` and the Console's `/plan-usage`
//! refresh it on demand with official non-billed reads, at most once a
//! minute per Harness, and never on a background timer. Both show the
//! Fleet by default once it has one, grouping shared logins. A Command
//! routed by the User config's routes reads it before each session Step
//! ([`router`]), refreshing a stale snapshot of a Harness whose read reports
//! Plan windows first, and never asks a Fleet peer.

use std::time::Duration;

use anyhow::{Result, bail};
use chrono::{TimeDelta, Utc};

pub mod exhaustion;
pub(crate) mod fleet;
pub(crate) mod observation;
mod read;
pub mod route;
pub mod router;
mod store;
mod view;

pub use exhaustion::Exhaustion;
pub use observation::Observation;
pub use route::Routing;
pub use router::Router;
use store::Store;
pub(crate) use view::EMPTY;
pub use view::View;

use crate::config::UserConfig;
use crate::harness::{Choice, Harness};

/// How long a Harness's non-billed read stays fresh for the view.
const FRESH: Duration = Duration::from_secs(60);

/// Which machines `thirdshift plan-usage` shows.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub enum Selection {
    /// The Fleet once a machine is paired or saved, else this machine.
    #[default]
    Default,
    Fleet,
    /// One machine by its Fleet name; this machine's own name is `Local`.
    Machine(String),
    /// This machine alone, as a Fleet machine is asked.
    Local,
}

/// What `thirdshift plan-usage` was asked to do.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Action {
    Show {
        selection: Selection,
        json: bool,
    },
    /// Forget recorded cooldowns for one Harness, or all with none.
    Clear {
        harness: Option<Harness>,
        json: bool,
    },
    /// Send this machine's saved Plan usage to each report destination, or
    /// the one named.
    Push {
        destination: Option<String>,
    },
}

/// What a Plan usage view shows: one machine's rows, or the Fleet's logins.
pub enum Shown {
    Local(View),
    Fleet(fleet::Fleet),
}

impl Shown {
    pub fn json(&self) -> Result<serde_json::Value> {
        Ok(match self {
            Self::Local(view) => serde_json::to_value(view)?,
            Self::Fleet(fleet) => serde_json::to_value(fleet)?,
        })
    }
}

impl std::fmt::Display for Shown {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Local(view) => view.fmt(f),
            Self::Fleet(fleet) => fleet.fmt(f),
        }
    }
}

/// Save what running sessions observed. Plan usage is evidence, never the
/// session's outcome, so a snapshot that can't be written costs nothing.
pub(crate) fn record(observations: Vec<Observation>) {
    if observations.is_empty() || cfg!(test) {
        return;
    }
    let Ok(store) = Store::machine() else {
        return;
    };
    let now = Utc::now();
    let _ = store.update_all(|harnesses| {
        for observation in &observations {
            harnesses
                .entry(observation.harness.name().into())
                .or_default()
                .observe(observation, "session", now);
        }
    });
}

/// Whether a headless session on `choice` may spend credit balances once
/// its included Plan windows are used up: only when it runs as a User
/// config route with `allow_credits = true`.
pub(crate) fn credits_allowed(choice: &Choice) -> bool {
    if cfg!(test) {
        return false;
    }
    UserConfig::load().is_ok_and(|config| config.routing.allows_credits(choice, &config.harness))
}

/// The route sessions that can't move between routes keep to, as a Triage
/// run's machine-reading sandbox binds one Harness's files: the first of
/// the User config's routes that could take a session now by this
/// machine's Plan usage, else `harness`. A choice the routes did not make
/// stays as it is.
pub fn settled_route(harness: &Choice) -> Choice {
    if harness.chosen_by != crate::harness::ChosenBy::Routes {
        return harness.clone();
    }
    let Ok(config) = UserConfig::load() else {
        return harness.clone();
    };
    let router = Router::of(&config.harness, &config.routing, harness, None, None);
    router
        .pick(false, &[])
        .and_then(|picked| router.candidates(false).get(picked.index))
        .map_or_else(|| harness.clone(), |candidate| candidate.choice.clone())
}

/// `harness` as a subscription Harness for `--clear`.
pub fn subscription_named(name: &str) -> Result<Harness> {
    match Harness::named(name) {
        Some(harness) if observation::subscription(harness) => Ok(harness),
        _ => bail!(
            "{name:?} is not a subscription Harness: Plan usage watches {}",
            observation::SUBSCRIPTION.map(Harness::name).join(", ")
        ),
    }
}

/// Run each installed readable Harness's non-billed read whose last one is
/// more than a minute old, side by side.
fn refresh(store: &Store) -> Result<()> {
    let saved = store.read()?;
    let now = Utc::now();
    let stale: Vec<Harness> = read::READABLE
        .into_iter()
        .filter(|harness| harness.installed())
        .filter(|harness| !read_lately(saved.get(harness.name()), now))
        .collect();
    read_into(store, &stale)
}

/// Whether `state`'s non-billed read ran within the last minute, so it is
/// not run again yet.
fn read_lately(state: Option<&store::State>, now: chrono::DateTime<Utc>) -> bool {
    let fresh = TimeDelta::from_std(FRESH).expect("a minute fits");
    state
        .and_then(|state| state.read_at)
        .is_some_and(|read| read <= now && now - read < fresh)
}

/// Run each of `stale`'s non-billed reads side by side, and take their
/// answers into the snapshot.
fn read_into(store: &Store, stale: &[Harness]) -> Result<()> {
    let read: Vec<(Harness, read::Reading)> = std::thread::scope(|scope| {
        let reads: Vec<_> = stale
            .iter()
            .map(|harness| scope.spawn(move || read::read(*harness).map(|read| (*harness, read))))
            .collect();
        reads
            .into_iter()
            .filter_map(|read| read.join().ok().flatten())
            .collect()
    });
    if read.is_empty() {
        return Ok(());
    }
    // Sessions may have written meanwhile: take the answers into the
    // snapshot as it is now.
    let now = Utc::now();
    store.update_all(|harnesses| {
        for (harness, reading) in read {
            reading.apply(harnesses.entry(harness.name().into()).or_default(), now);
        }
    })
}

/// This machine's view, after refreshing its non-billed reads.
fn local_view(config: &UserConfig) -> Result<View> {
    let store = Store::machine()?;
    refresh(&store)?;
    Ok(View::of(
        config,
        store.read()?,
        Harness::installed,
        Utc::now(),
    ))
}

/// This machine's view from what is saved, running no read: what the
/// Console header and a pushed report show.
pub(crate) fn saved_view(config: &UserConfig) -> Result<View> {
    Ok(View::of(
        config,
        Store::machine()?.read()?,
        Harness::installed,
        Utc::now(),
    ))
}

/// The view `selection` asks for, from what `capture` took of the Fleet:
/// read on behalf of its person when a Console reads for someone signed in.
pub(crate) fn show(
    config: &UserConfig,
    selection: &Selection,
    capture: &fleet::Capture<'_>,
) -> Result<Shown> {
    let reach = match selection {
        Selection::Machine(name) if name != capture.local() => fleet::Reach::Machine(name),
        Selection::Fleet => fleet::Reach::Fleet(local_view(config)?),
        Selection::Default if capture.default_view() => fleet::Reach::Fleet(local_view(config)?),
        Selection::Local | Selection::Machine(_) | Selection::Default => {
            return Ok(Shown::Local(local_view(config)?));
        }
    };
    Ok(Shown::Fleet(capture.load(reach)?))
}

/// Forget recorded cooldowns on this machine, and say which Harnesses'.
pub(crate) fn clear(harness: Option<Harness>) -> Result<Vec<&'static str>> {
    Store::machine()?.clear(harness)?;
    Ok(match harness {
        Some(harness) => vec![harness.name()],
        None => observation::SUBSCRIPTION.map(Harness::name).to_vec(),
    })
}

/// Before routing a session Step, run the non-billed read of each of
/// `harnesses` that reports Plan windows ([`read::WINDOWED`]) and is
/// installed, when its saved snapshot is stale for routing, side by side.
/// Only this machine is read.
fn refresh_for_routing(store: &Store, harnesses: &[Harness]) -> Result<()> {
    let saved = store.read()?;
    let now = Utc::now();
    let mut stale: Vec<Harness> = Vec::new();
    for harness in harnesses {
        if read::WINDOWED.contains(harness)
            && !stale.contains(harness)
            && harness.installed()
            && !read_lately(saved.get(harness.name()), now)
            && router::stale(saved.get(harness.name()), now)
        {
            stale.push(*harness);
        }
    }
    read_into(store, &stale)
}

/// Whether a Pass whose sessions would run on `harness`, a Security run's
/// when `security`, finds every route it may take unavailable by this
/// machine's Plan usage, refreshing a stale snapshot of a Harness whose
/// read reports Plan windows first. Only a choice the User config's routes
/// made walks them; any other is that Harness alone, held only at confirmed
/// exhaustion. Never asks a Fleet peer, and none in unit tests.
pub fn pass_exhaustion(
    config: &UserConfig,
    harness: &Choice,
    security: bool,
) -> Option<Exhaustion> {
    if cfg!(test) {
        return None;
    }
    let routes = allowed_routes(config, harness, security);
    let store = Store::machine().ok()?;
    let harnesses: Vec<Harness> = routes.iter().map(|route| route.harness).collect();
    let _ = refresh_for_routing(&store, &harnesses);
    let saved = store.read().ok()?;
    exhaustion::judge(
        &routes,
        &config.routing,
        &saved,
        Harness::installed,
        Utc::now(),
    )
}

/// The routes a Pass on `harness` may take, in order.
fn allowed_routes(config: &UserConfig, harness: &Choice, security: bool) -> Vec<route::Route> {
    let router = Router::of(
        &config.harness,
        &config.routing,
        harness,
        Choice::of_security_review(config.security_harness, &config.harness).as_ref(),
        Some(&Choice::of(
            &crate::harness::Asked::default(),
            &config.harness,
        )),
    );
    router.allowed(security, harness.harness)
}

/// Whether every route a factory Command started with no Harness flags
/// would take on this machine is unavailable by its saved Plan usage, so
/// scheduled Passes are skipping: `harness.routes`, else `harness.default`
/// alone. Reads only the saved snapshot, never a Harness or a Fleet peer,
/// and none in unit tests.
pub fn machine_exhaustion(config: &UserConfig) -> Option<Exhaustion> {
    if cfg!(test) {
        return None;
    }
    let routes = if config.routing.routes.is_empty() {
        vec![exhaustion::pinned(
            config.harness.default.unwrap_or(Harness::Claude),
        )]
    } else {
        config.routing.routes.clone()
    };
    let saved = Store::machine().ok()?.read().ok()?;
    exhaustion::judge(
        &routes,
        &config.routing,
        &saved,
        Harness::installed,
        Utc::now(),
    )
}

/// The latest Plan usage limit still holding a Harness on this machine, as
/// a Paused Command's record keeps it, for a Spec run whose Ticket's child
/// Run, or a Run whose Base fix, paused and reports only that it did: the
/// most recent cooldown, else what holds the routes a Command with no
/// Harness flags would take. None in unit tests.
pub(crate) fn latest_limit() -> Option<crate::session::limits::Limit> {
    if cfg!(test) {
        return None;
    }
    let saved = Store::machine().ok()?.read().ok()?;
    let now = Utc::now();
    let cooled = saved
        .iter()
        .filter_map(|(name, state)| Some((Harness::named(name)?, state)))
        .filter_map(|(harness, state)| Some((harness, state, state.cooldown.as_ref()?)))
        .filter(|(_, _, cooldown)| cooldown.until > now)
        .max_by_key(|(_, _, cooldown)| cooldown.since);
    match cooled {
        Some((harness, state, cooldown)) => {
            let used = cooldown
                .window
                .as_deref()
                .and_then(|window| state.used_percent_in(window, now));
            Some(crate::session::limits::Limit::of(
                harness,
                cooldown.window.clone(),
                used,
                Some(cooldown.until),
            ))
        }
        None => machine_exhaustion(&UserConfig::load().ok()?).map(|ex| ex.limit()),
    }
}

/// The status banner for a machine whose every configured default route
/// is unavailable by Plan usage: the routes held and the earliest known
/// reset.
pub fn banner(config: &UserConfig) -> Option<String> {
    let exhaustion = machine_exhaustion(config)?;
    let mut line = format!(
        "Plan usage: every configured route is unavailable, so scheduled Passes skip: {}",
        exhaustion.routes()
    );
    if let Some(reset) = exhaustion.earliest_reset() {
        line.push_str(&format!(
            "; earliest reset {}",
            reset.to_rfc3339_opts(chrono::SecondsFormat::Secs, true)
        ));
    }
    Some(line)
}

/// `thirdshift plan-usage`.
pub fn execute(action: Action) -> Result<String> {
    match action {
        Action::Push { destination } => {
            crate::console::report::push_plan_usage_by_hand(destination.as_deref())
        }
        Action::Clear { harness, json } => {
            let cleared = clear(harness)?;
            if json {
                return Ok(serde_json::to_string_pretty(
                    &serde_json::json!({"version": 1, "cleared": cleared}),
                )?);
            }
            Ok(format!(
                "Cleared recorded Plan usage cooldowns and revalidation for {}",
                cleared.join(", ")
            ))
        }
        Action::Show { selection, json } => {
            let config = UserConfig::load()?;
            let shown = show(&config, &selection, &fleet::Capture::new(&config, None))?;
            if json {
                Ok(serde_json::to_string_pretty(&shown.json()?)?)
            } else {
                Ok(shown.to_string())
            }
        }
    }
}