layover_http/

generated.rs

//! The Layover HTTP surface, generated from `api/openapi.yaml`.
//!
//! @generated by `cargo xtask generate-api`. Do not edit by hand: `cargo xtask verify`
//! regenerates this file and fails if the result differs, so an edit here is reverted
//! rather than kept. Change the specification instead.
//!
//! Source: Layover Tower API v0.23.1

#![allow(clippy::too_many_lines)]

use axum::response::IntoResponse as _;
use serde::{Deserialize, Serialize};

use crate::EventStream;

/// Whether an agent writes to the shared workspace or gets a snapshot.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum Access {
    /// `read-only`
    #[serde(rename = "read-only")]
    ReadOnly,
    /// `read-write`
    #[serde(rename = "read-write")]
    ReadWrite,
}

/// One configured agent.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Agent {
    /// Whether the agent writes to the shared workspace.
    pub access: Access,
    /// One line saying what the agent is.
    #[serde(default)]
    pub description: Option<String>,
    /// Whether a human may send flights straight to this agent.
    pub entry: bool,
    /// Model identifier passed to the runner.
    #[serde(default)]
    pub model: Option<String>,
    /// The key the agent is declared under, and what routes refer to.
    pub name: String,
    /// A longer statement of when to route work here.
    #[serde(default)]
    pub purpose: Option<String>,
    /// Whether the agent is pinned resident rather than transient.
    pub resident: bool,
    /// Which runner invokes this agent's CLI.
    #[serde(default)]
    pub runner: Option<String>,
}

/// The factory's agents and the edges between them.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct AgentList {
    /// Every configured agent.
    pub agents: Vec<Agent>,
    /// The route map.
    pub routes: Vec<Route>,
}

/// What kind of thing an agent is stuck on. Coarse on purpose: the point is to make "half my
/// runs are stuck on credentials" visible at a glance, with the detail in the prose.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum Blocker {
    /// `access`
    #[serde(rename = "access")]
    Access,
    /// `tooling`
    #[serde(rename = "tooling")]
    Tooling,
    /// `ambiguity`
    #[serde(rename = "ambiguity")]
    Ambiguity,
    /// `environment`
    #[serde(rename = "environment")]
    Environment,
    /// `decision`
    #[serde(rename = "decision")]
    Decision,
    /// `other`
    #[serde(rename = "other")]
    Other,
}

/// One named slice of spend, such as an agent or a model.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct CostBucket {
    /// The agent or model this slice belongs to.
    pub name: String,
    /// Totals for this slice.
    pub summary: CostSummary,
}

/// Where the factory's money went.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct CostReport {
    /// Spend per agent, most expensive first.
    pub by_agent: Vec<CostBucket>,
    /// Spend per model, most expensive first. Runs with no reported model are omitted.
    pub by_model: Vec<CostBucket>,
    /// Spend per workflow, most expensive first. The breakdown a factory with several
    /// pipelines actually needs: per-agent totals cannot answer "what does the nightly sweep
    /// cost" once an agent belongs to more than one workflow, and most of them do.
    pub by_pipeline: Vec<CostBucket>,
    /// The factory-wide ceiling and what is left of it.
    pub reserve: ReserveState,
    /// The period these totals cover, including the zone it was reckoned in and whether it
    /// outruns retention. Part of the number, not decoration.
    pub span: WindowSpan,
    /// Totals across every run in scope.
    pub total: CostSummary,
}

/// Where a cost figure came from, worst-first. `reported` is the only kind worth billing
/// against; `rate_card` was derived from token counts and published prices; `unreported`
/// means the runner said nothing, so the figure is zero and means nothing.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum CostSource {
    /// `reported`
    #[serde(rename = "reported")]
    Reported,
    /// `rate_card`
    #[serde(rename = "rate_card")]
    RateCard,
    /// `unreported`
    #[serde(rename = "unreported")]
    Unreported,
}

/// Totals over some set of runs, carrying their own confidence.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct CostSummary {
    /// The weakest source contributing to this total.
    pub confidence: CostSource,
    /// Runs priced from a rate card rather than measured.
    pub estimated_runs: i32,
    /// Fraction of runs whose cost the runner actually reported, 0.0 to 1.0.
    pub measured_share: f64,
    /// How many runs contributed.
    pub runs: i32,
    /// Runs whose runner reported no cost at all.
    pub unreported_runs: i32,
    /// Total tokens.
    pub usage: TokenUsage,
    /// Total cost in US dollars.
    pub usd: f64,
}

/// A period to report over.
///
/// Two kinds, and the difference matters. `today` and `month_to_date` are **calendar** windows: they
/// begin at local midnight, so which instant that is depends on the Tower's time zone. The
/// rest are **rolling**: a fixed number of hours ending now, identical everywhere.
///
/// Conflating the two is not theoretical. Gating spend on a UTC day boundary while reporting
/// the ledger in local time lets a factory spend one day's money twice, and the bug is
/// invisible until it matters.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum CostWindow {
    /// `today`
    #[serde(rename = "today")]
    Today,
    /// `last_24h`
    #[serde(rename = "last_24h")]
    Last24h,
    /// `last_7d`
    #[serde(rename = "last_7d")]
    Last7d,
    /// `last_30d`
    #[serde(rename = "last_30d")]
    Last30d,
    /// `month_to_date`
    #[serde(rename = "month_to_date")]
    MonthToDate,
    /// `last_90d`
    #[serde(rename = "last_90d")]
    Last90d,
    /// `all_time`
    #[serde(rename = "all_time")]
    AllTime,
}

/// A boolean parameter a pipeline accepts at trigger time.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Flag {
    /// Value used when the trigger does not set the flag.
    pub default: bool,
    /// What turning this flag on actually does.
    #[serde(default)]
    pub description: Option<String>,
    /// The name a prompt tests with `@include(name)`.
    pub name: String,
}

/// A flag resolved to the value one run will see. Distinct from `Flag`, which declares what a pipeline accepts: a declaration carries a default, and reporting that default back as though it were the operator's choice would hide the difference between a flag left alone and a flag deliberately set to the same value.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct FlagValue {
    /// The name a prompt tests with `@include(name)`.
    pub name: String,
    /// The value this run will see.
    pub value: bool,
}

/// Confirmation that work has been started.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct FlightAccepted {
    /// Identifier of the flight that was created.
    pub flight_id: String,
    /// Identifier of the new chain, which carries Hops and Fuel.
    pub itinerary_id: String,
    /// The agent the flight was addressed to.
    pub to: String,
}

/// Whether everything is halted.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct GroundStop {
    /// True when no new work may start.
    pub engaged: bool,
    /// When the Ground Stop was engaged.
    #[serde(default)]
    pub since: Option<String>,
}

/// Whether the Tower is up and whether it is allowed to do anything.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Health {
    /// True when a Ground Stop is engaged and no new work may start.
    pub ground_stop: bool,
    /// Always `ok`; failure is signalled by not answering at all.
    pub status: Status,
    /// The Tower's own version.
    pub version: String,
}

/// Matching help requests, most recent first.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct HelpList {
    /// How many of them nobody has dealt with.
    pub open: i32,
    /// The requests.
    pub requests: Vec<HelpRequest>,
}

/// One agent asking a human for something.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct HelpRequest {
    /// Who is asking.
    pub agent: String,
    /// When it was raised.
    pub at: String,
    /// What kind of thing is in the way.
    pub blocker: Blocker,
    /// What was tried, what happened, and what is needed.
    pub detail: String,
    /// Whether this stopped the work or merely limited it. An agent can finish its task and
    /// still have been unable to check something; that is worth reporting and is not an
    /// outage.
    pub fatal: bool,
    /// The chain it belonged to.
    pub itinerary_id: String,
    /// The workflow whose run raised it, derived from the itinerary rather than stored on the
    /// request. Null when no run for that itinerary is still in history, which retention can
    /// cause at the far edge of the window.
    #[serde(default)]
    pub pipeline: Option<String>,
    /// When a human marked it dealt with. Null while it is still open.
    #[serde(default)]
    pub resolved_at: Option<String>,
    /// The run that raised it.
    pub run_id: String,
    /// One line, for a list.
    pub summary: String,
}

/// The result of resolving.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct HelpResolved {
    /// How many open requests were marked. Zero is not an error: somebody else may have
    /// resolved them, or the narrowing may have matched nothing.
    pub resolved: i32,
}

/// How much applying a learning would change a future run. Self-assessed, and therefore used
/// for display and triage only — never to decide whether a learning applies.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum Impact {
    /// `low`
    #[serde(rename = "low")]
    Low,
    /// `medium`
    #[serde(rename = "medium")]
    Medium,
    /// `high`
    #[serde(rename = "high")]
    High,
}

/// One causal chain of flights, and the budget it shares.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Itinerary {
    /// Agents that ran in this chain, in the order they first ran.
    #[serde(default)]
    pub agents: Option<Vec<String>>,
    /// Why a chain is stalled or halted, when that can be said.
    #[serde(default)]
    pub detail: Option<String>,
    /// When the last run of the chain ended. Null while it is still working.
    #[serde(default)]
    pub finished_at: Option<String>,
    /// Identifier of the chain.
    pub itinerary_id: String,
    /// False when any run in the chain reported no cost. A total built partly from silence is
    /// a floor, not a figure, and showing it as though it were measured invites planning
    /// against it.
    #[serde(default)]
    pub measured: Option<bool>,
    /// The pipeline it was triggered through, when one was named.
    #[serde(default)]
    pub pipeline: Option<String>,
    /// How many runs the chain has started.
    pub runs: i32,
    /// When the first run of the chain began.
    pub started_at: String,
    /// What became of the chain.
    pub state: ItineraryState,
    /// What the chain has spent, as far as its runners reported.
    pub usd: f64,
}

/// Chains of work.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ItineraryList {
    /// Chains, most recently started first.
    pub itineraries: Vec<Itinerary>,
    /// How many of them are stalled. Counted separately so the number can be shown without
    /// reading the list, because it is the one that should prompt somebody to look.
    pub stalled: i32,
}

/// What became of a chain.
///
/// `stalled` is the one that matters and the one a list of runs cannot show: every run
/// succeeded, nothing is live, nothing is queued, and nothing will ever happen again. It is
/// the failure mode this whole surface exists to make visible.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum ItineraryState {
    /// `working`
    #[serde(rename = "working")]
    Working,
    /// `finished`
    #[serde(rename = "finished")]
    Finished,
    /// `stalled`
    #[serde(rename = "stalled")]
    Stalled,
    /// `halted`
    #[serde(rename = "halted")]
    Halted,
}

/// The condition under which a rendezvous barrier releases.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum Join {
    /// `all`
    #[serde(rename = "all")]
    All,
    /// `any`
    #[serde(rename = "any")]
    Any,
}

/// A person's verdict on a learning.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct JudgeLearningRequest {
    /// The verdict.
    pub state: Judgement,
}

/// What a person decided about a learning that is already in use.
///
/// There is no `provisional` here. A learning starts provisional on its own and becomes
/// confirmed through independent rediscovery; putting one *back* would discard evidence
/// already gathered.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum Judgement {
    /// `confirmed`
    #[serde(rename = "confirmed")]
    Confirmed,
    /// `rejected`
    #[serde(rename = "rejected")]
    Rejected,
}

/// Something an agent worked out, with its history.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Learning {
    /// The agent this applies to. Learnings do not cross agents.
    pub agent: String,
    /// When it was first proposed.
    pub first_at: String,
    /// Identifier.
    pub id: String,
    /// The agent's own rating, for triage.
    pub impact: Impact,
    /// When it was most recently proposed.
    pub last_at: String,
    /// How many times it has been independently rediscovered, including the first proposal.
    /// Repeating advice the agent was just shown does not count — an echo is not evidence.
    pub proposals: i32,
    /// Runs before it lapses. Meaningless unless `provisional`.
    pub runs_left: i32,
    /// Where it is in its life.
    pub state: LearningState,
    /// The insight.
    pub text: String,
}

/// Matching learnings.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct LearningList {
    /// How many of them are currently given to runs.
    pub active: i32,
    /// The learnings.
    pub learnings: Vec<Learning>,
}

/// Where a learning is in its life. `provisional` applies now and will lapse unless
/// rediscovered; `confirmed` has been rediscovered enough times to be treated as real;
/// `lapsed` is remembered only so a later rediscovery can be recognised as one; `rejected`
/// was refused by a human and never counts again.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum LearningState {
    /// `provisional`
    #[serde(rename = "provisional")]
    Provisional,
    /// `confirmed`
    #[serde(rename = "confirmed")]
    Confirmed,
    /// `lapsed`
    #[serde(rename = "lapsed")]
    Lapsed,
    /// `rejected`
    #[serde(rename = "rejected")]
    Rejected,
}

/// A flight that has been asked for and not yet dispatched.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PendingFlight {
    /// The prompt the run will be given.
    pub body: String,
    /// The flags set for this run.
    #[serde(default)]
    pub flags: Option<Vec<FlagValue>>,
    /// Identifier of the queued flight.
    pub flight_id: String,
    /// The chain it will begin.
    pub itinerary_id: String,
    /// The pipeline it was triggered through, when one was named.
    #[serde(default)]
    pub pipeline: Option<String>,
    /// When it was asked for.
    pub queued_at: String,
    /// The agent it is addressed to.
    pub to: String,
}

/// Work waiting to start.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PendingList {
    /// What will pick this work up, or null when nothing will. Null is the honest answer
    /// until the supervisor exists, and the dashboard says so rather than showing a queue
    /// that looks like it is moving.
    #[serde(default)]
    pub dispatched_by: Option<String>,
    /// Queued flights, oldest first.
    pub pending: Vec<PendingFlight>,
}

/// A named entry point into the mesh.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Pipeline {
    /// One line saying what this pipeline is for.
    #[serde(default)]
    pub description: Option<String>,
    /// The agent that receives the first flight.
    pub entry: String,
    /// The boolean parameters this pipeline accepts.
    pub flags: Vec<Flag>,
    /// Shared budget for a chain started here, honouring the entry agent's own `fuel_usd`
    /// where it sets one. Bounds **breadth**, which is the dimension Hops cannot see.
    pub fuel_usd: f64,
    /// Flights a chain started here may make before it is cut. Bounds **depth**: branches
    /// inherit the remaining count rather than splitting it, so this says nothing about how
    /// wide a fan-out spreads.
    pub max_hops: i32,
    /// The key the pipeline is declared under.
    pub name: String,
    /// True when this pipeline picks up booked layovers rather than starting fresh work. A
    /// tick that finds nothing due costs nothing.
    pub resumes: bool,
    /// What starts it.
    pub trigger: Trigger,
    /// Whether instances of this pipeline share a working directory or get one each. A
    /// schedule fires whether or not the last instance finished, so anything reaching a
    /// read-write agent wants its own.
    pub workspace: Workspace,
}

/// Every declared pipeline.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PipelineList {
    /// The pipelines.
    pub pipelines: Vec<Pipeline>,
}

/// An error, shaped after RFC 9457.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Problem {
    /// An explanation specific to this occurrence.
    #[serde(default)]
    pub detail: Option<String>,
    /// The HTTP status code, repeated in the body for clients that lose it.
    pub status: i32,
    /// A short, human-readable summary of the problem.
    pub title: String,
}

/// What an agent wrote about its own run.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Report {
    /// Which agent wrote it.
    pub agent: String,
    /// What the run produced or changed — paths, branch names, pull request identifiers.
    /// Separate from the body so output can be found without reading the prose.
    #[serde(default)]
    pub artifacts: Option<Vec<String>>,
    /// When it was written.
    pub at: String,
    /// The report itself, as the agent wrote it.
    pub body: String,
    /// One line, for a list. What happened, not what was attempted.
    pub headline: String,
    /// The chain it belonged to.
    pub itinerary_id: String,
    /// The run this describes.
    pub run_id: String,
    /// True when the report was longer than the cap and was cut. Worth knowing: otherwise it
    /// reads as though the agent simply stopped there.
    #[serde(default)]
    pub trimmed: Option<bool>,
}

/// The factory-wide spend ceiling. Distinct from Fuel, which bounds one itinerary: a
/// scheduled pipeline mints a fresh itinerary with a fresh Fuel budget on every tick, so
/// only the Reserve bounds the total. The window rolls rather than resetting at midnight.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ReserveState {
    /// Ceiling for the window. Null when no ceiling is enforced.
    #[serde(default)]
    pub cap_usd: Option<f64>,
    /// True when the Reserve is currently refusing new work.
    pub exhausted: bool,
    /// Left before new work is refused. Null when unlimited.
    #[serde(default)]
    pub remaining_usd: Option<f64>,
    /// Spend within the current window.
    pub spent_usd: f64,
    /// How far back the rolling window reaches.
    pub window_hours: i64,
}

/// Which open help requests to mark as dealt with.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ResolveHelpRequest {
    /// Only requests from this agent.
    #[serde(default)]
    pub agent: Option<String>,
    /// Only requests of this kind.
    #[serde(default)]
    pub blocker: Option<Blocker>,
    /// Only requests raised by this run. The narrowest form, and the one a list with a button
    /// beside each row uses.
    #[serde(default)]
    pub run_id: Option<String>,
    /// How far back to look. Defaults to the last 30 days.
    #[serde(default)]
    pub window: Option<CostWindow>,
}

/// One entry of the route map, possibly expanding to several edges.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Route {
    /// Sending agents.
    pub from: Vec<String>,
    /// Set when flights on this edge are parked at a rendezvous barrier.
    #[serde(default)]
    pub join: Option<Join>,
    /// Backstop for a barrier that never completes.
    #[serde(default)]
    pub timeout_sec: Option<i64>,
    /// Receiving agents.
    pub to: Vec<String>,
}

/// The factory drawn as a graph.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct RouteMap {
    /// Which file it was generated from.
    #[serde(default)]
    pub config_path: Option<String>,
    /// When the configuration was read.
    pub generated_at: String,
    /// Mermaid `flowchart` source, ready to render.
    pub mermaid: String,
}

/// One supervised CLI execution.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Run {
    /// Which agent was run.
    pub agent: String,
    /// What the run could not get past, when it asked for help. Independent of `status`: an
    /// agent can finish its task and still have been unable to check something. Without it a
    /// blocked run looks exactly like a clean one on a list.
    #[serde(default)]
    pub blocked_on: Option<String>,
    /// Where `cost_usd` came from.
    pub cost_source: CostSource,
    /// Null when the runner reported no cost, which the Tower logs loudly.
    #[serde(default)]
    pub cost_usd: Option<f64>,
    /// Why the run ended, for the outcomes where that is not self-evident.
    #[serde(default)]
    pub detail: Option<String>,
    /// How long the run took. Null while it is still going, and also null if the clock moved
    /// backwards between the two readings — a negative duration on a dashboard is worse than
    /// an absent one, because somebody will average it.
    #[serde(default)]
    pub duration_sec: Option<i64>,
    /// Process exit code, when there was one.
    #[serde(default)]
    pub exit_code: Option<i32>,
    /// When the process exited; null while it is still running.
    #[serde(default)]
    pub finished_at: Option<String>,
    /// Hops left when this run was started, mirrored for display only.
    #[serde(default)]
    pub hops_remaining: Option<i32>,
    /// The chain this run belongs to.
    pub itinerary_id: String,
    /// Which model the runner used, when it said.
    #[serde(default)]
    pub model: Option<String>,
    /// The pipeline that started this run's chain, when one did.
    #[serde(default)]
    pub pipeline: Option<String>,
    /// Identifier of this run.
    pub run_id: String,
    /// When the process was spawned.
    pub started_at: String,
    /// How it ended, or that it has not.
    pub status: RunStatus,
}

/// Matching runs, newest first.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct RunList {
    /// The runs.
    pub runs: Vec<Run>,
}

/// How a run ended, or that it has not.
///
/// `halted` is deliberately distinct from `failed`: a rail stopping work — Hops, Fuel, the
/// run cap or the Reserve — is the system doing its job, and colouring it like a crash
/// teaches people to ignore the colour. `interrupted` means the run was alive when the Tower
/// went away; it is recoverable, and recovery starts a new run rather than resuming this one.
///
/// There is no `stalled` here. Stalling is something an *itinerary* does when it parks at a
/// barrier that never releases; a run either finishes or does not.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum RunStatus {
    /// `running`
    #[serde(rename = "running")]
    Running,
    /// `succeeded`
    #[serde(rename = "succeeded")]
    Succeeded,
    /// `failed`
    #[serde(rename = "failed")]
    Failed,
    /// `timed_out`
    #[serde(rename = "timed_out")]
    TimedOut,
    /// `halted`
    #[serde(rename = "halted")]
    Halted,
    /// `interrupted`
    #[serde(rename = "interrupted")]
    Interrupted,
}

/// Exactly one of `pipeline` and `to` must be given, and flags are only accepted alongside a
/// pipeline, because a pipeline is what declares them.
///
/// Neither is marked required here because JSON Schema cannot state "exactly one of these"
/// in a way this generator supports. The Tower enforces it and answers `400` — so a client
/// that satisfies this schema can still be rejected.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SendFlightRequest {
    /// What the receiving agent is being asked to do.
    pub body: String,
    /// Flag overrides, keyed by flag name. Unset flags take their declared default.
    #[serde(default)]
    pub flags: Option<std::collections::BTreeMap<String, bool>>,
    /// Name of the pipeline to start.
    #[serde(default)]
    pub pipeline: Option<String>,
    /// Name of an `entry = true` agent to send to directly.
    #[serde(default)]
    pub to: Option<String>,
}

/// Liveness of the Tower itself.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum Status {
    /// `ok`
    #[serde(rename = "ok")]
    Ok,
}

/// Tokens consumed. Cached reads and writes are counted apart from fresh input because
/// providers price them very differently, and blending them makes any derived cost wrong by
/// whatever the cache hit rate happened to be.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct TokenUsage {
    /// Tokens served from the provider's prompt cache.
    pub cache_read: i64,
    /// Tokens written into the provider's prompt cache.
    pub cache_write: i64,
    /// Prompt tokens billed at the input rate.
    pub input: i64,
    /// Generated tokens.
    pub output: i64,
}

/// What starts a pipeline.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Trigger {
    /// Set when the pipeline fires on a five-field cron expression.
    #[serde(default)]
    pub cron: Option<String>,
    /// Set when the pipeline fires on a fixed interval.
    #[serde(default)]
    pub every_seconds: Option<i64>,
    /// Whether a human or a clock starts this pipeline.
    pub kind: TriggerKind,
}

/// Whether a human or a clock starts a pipeline.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum TriggerKind {
    /// `manual`
    #[serde(rename = "manual")]
    Manual,
    /// `scheduled`
    #[serde(rename = "scheduled")]
    Scheduled,
}

/// A resolved window, and an honest account of how it was arrived at.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct WindowSpan {
    /// True when the start was reckoned against a local midnight.
    pub calendar: bool,
    /// When the period ends, which is the moment it was resolved.
    pub end: String,
    /// A human label, such as "Last 30 days".
    pub label: String,
    /// When the period begins. Null means from the beginning of what is kept.
    #[serde(default)]
    pub start: Option<String>,
    /// True when the period reaches further back than retention keeps, which makes the
    /// totals a lower bound rather than a total.
    pub truncated: bool,
    /// Which window this is.
    pub window: CostWindow,
    /// The IANA zone the start was reckoned in, or null for a rolling window. The absence is
    /// the point: nobody should have to wonder which zone "last 7 days" used.
    #[serde(default)]
    pub zone: Option<String>,
}

/// Whether instances of one pipeline share a working directory or get one each. A schedule
/// fires whether or not the last instance finished, so anything reaching a read-write agent
/// wants its own.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum Workspace {
    /// `shared`
    #[serde(rename = "shared")]
    Shared,
    /// `per-itinerary`
    #[serde(rename = "per-itinerary")]
    PerItinerary,
}

/// query parameters for `getCosts`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct GetCostsQuery {
    /// The period to total over. Defaults to the last 30 days.
    ///
    /// Note that `today` and `month_to_date` are *calendar* windows and the rest are *rolling* ones.
    /// A rolling window is the same length everywhere; a calendar one begins at local
    /// midnight and therefore depends on where the Tower is standing. The response says
    /// which zone was used, so the figure can be read without having to guess.
    #[serde(default)]
    pub window: Option<CostWindow>,
    /// Narrow the totals, the per-agent and the per-model breakdowns to one workflow.
    ///
    /// `reserve` is deliberately unaffected. The Reserve caps the whole factory, so reporting
    /// it against one workflow's spend would describe a rail that does not exist.
    #[serde(default)]
    pub pipeline: Option<String>,
}

/// path parameters for `cancelFlight`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct CancelFlightPath {
    /// Identifier of the queued flight.
    pub flight_id: String,
}

/// query parameters for `getGraph`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct GetGraphQuery {
    /// Draw only what this pipeline sets in motion. Omit for the whole factory.
    ///
    /// A factory holds several pipelines and they are genuinely separate workflows — a
    /// nightly sweep has nothing to do with taking a work item to a pull request. Drawn
    /// together they read as one very confused process. An agent belonging to two workflows
    /// appears in both, which is the honest answer.
    #[serde(default)]
    pub pipeline: Option<String>,
}

/// query parameters for `listHelp`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ListHelpQuery {
    /// Only requests from this agent.
    #[serde(default)]
    pub agent: Option<String>,
    /// Only requests raised by a run of this workflow.
    #[serde(default)]
    pub pipeline: Option<String>,
    /// Only requests of this kind.
    #[serde(default)]
    pub blocker: Option<Blocker>,
    /// Only requests nobody has dealt with yet.
    #[serde(default)]
    pub open: Option<bool>,
    /// How far back to look. Defaults to the last 30 days.
    #[serde(default)]
    pub window: Option<CostWindow>,
}

/// query parameters for `listItineraries`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ListItinerariesQuery {
    /// How far back to look. Defaults to the last 24 hours, because a dashboard opening on
    /// ninety days of chains is answering a question nobody asked.
    #[serde(default)]
    pub window: Option<CostWindow>,
    /// Only chains in this state.
    #[serde(default)]
    pub state: Option<ItineraryState>,
}

/// query parameters for `listLearnings`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ListLearningsQuery {
    /// Only learnings belonging to this agent.
    #[serde(default)]
    pub agent: Option<String>,
    /// Only learnings in this state.
    #[serde(default)]
    pub state: Option<LearningState>,
}

/// path parameters for `judgeLearning`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct JudgeLearningPath {
    /// Identifier of the learning.
    pub learning_id: String,
}

/// query parameters for `listRuns`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ListRunsQuery {
    /// Return only runs in this state.
    #[serde(default)]
    pub status: Option<RunStatus>,
    /// Return only runs belonging to this itinerary.
    #[serde(default)]
    pub itinerary_id: Option<String>,
    /// Return only runs of this agent.
    #[serde(default)]
    pub agent: Option<String>,
    /// Return only runs whose chain was started by this pipeline.
    #[serde(default)]
    pub pipeline: Option<String>,
    /// How far back to look. Defaults to the last 24 hours, because a dashboard opening on
    /// ninety days of history is answering a question nobody asked.
    #[serde(default)]
    pub window: Option<CostWindow>,
    /// Maximum number of runs to return, newest first.
    #[serde(default)]
    pub limit: Option<i32>,
}

/// path parameters for `getRun`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct GetRunPath {
    /// Identifier of the run to fetch.
    pub run_id: String,
}

/// path parameters for `getReport`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct GetReportPath {
    /// Identifier of the run.
    pub run_id: String,
}

/// path parameters for `streamRun`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct StreamRunPath {
    /// Identifier of the run to stream.
    pub run_id: String,
}

/// Everything the Tower must implement to serve this API.
///
/// One method per `operationId`. Adding an operation to `api/openapi.yaml` adds a method
/// here, so an unimplemented endpoint is a compile error rather than a 404 discovered in
/// production.
pub trait Api: Send + Sync + 'static {
    /// Every configured agent and the route map between them.
    ///
    /// This is the UI's graph view, and it is also how a human answers "what can talk to what"
    /// without reading the TOML.
    ///
    /// `GET /agents`
    fn list_agents(&self) -> impl core::future::Future<Output = Result<AgentList, Problem>> + Send;
    /// What the factory has spent, and how much of that is measured.
    ///
    /// A single Fuel figure says whether a chain may continue. This says where the money went —
    /// per agent, per model — and, critically, how much of the total the runners actually
    /// reported rather than Layover inferring it from a rate card.
    ///
    /// Treat `confidence` as part of the number. A total that is mostly measured is still not
    /// measured, so any estimated or unreported run downgrades the whole figure.
    ///
    /// `GET /costs`
    fn get_costs(
        &self,
        query: GetCostsQuery,
    ) -> impl core::future::Future<Output = Result<CostReport, Problem>> + Send;
    /// Flights waiting for something to dispatch them.
    ///
    /// Work that has been asked for and not yet started. Until the supervisor exists this is
    /// everything anybody has triggered; afterwards it is the backlog.
    ///
    /// `GET /flights`
    fn list_pending(
        &self,
    ) -> impl core::future::Future<Output = Result<PendingList, Problem>> + Send;
    /// Start work by sending the first flight of a new itinerary.
    ///
    /// Give either a `pipeline` or a `to`. A pipeline is the normal way in: it names the entry
    /// agent and declares which flags may be set. A bare `to` sends to an agent marked
    /// `entry = true` and accepts no flags.
    ///
    /// **The flight is queued, not run.** Dispatching it needs the supervisor, which is not part
    /// of this release, so `202` means the work is booked and durable — it will start when there
    /// is something to start it. `GET /flights` shows what is waiting.
    ///
    /// `POST /flights`
    fn send_flight(
        &self,
        body: SendFlightRequest,
    ) -> impl core::future::Future<Output = Result<FlightAccepted, Problem>> + Send;
    /// Take a queued flight back off the queue.
    ///
    /// Only work that has not started can be cancelled. A run that is already going is stopped
    /// with a Ground Stop, which is a different decision with a different blast radius — one
    /// flight versus the whole factory — and conflating them would make the smaller action feel
    /// as dangerous as the larger one.
    ///
    /// `DELETE /flights/{flight_id}`
    fn cancel_flight(
        &self,
        path: CancelFlightPath,
    ) -> impl core::future::Future<Output = Result<PendingList, Problem>> + Send;
    /// The route map as a diagram, with what is happening drawn on it.
    ///
    /// Mermaid source, generated from the configuration as it is on disk right now. Edit
    /// `layover.toml` and reload; the diagram changes with it, because nothing here is baked at
    /// build time.
    ///
    /// Agents currently running, waiting at a barrier, or freshly failed are coloured. An edge
    /// into a joined agent from a sender the barrier does not name is drawn as bypassing it,
    /// which is what actually happens.
    ///
    /// `GET /graph`
    fn get_graph(
        &self,
        query: GetGraphQuery,
    ) -> impl core::future::Future<Output = Result<RouteMap, Problem>> + Send;
    /// Halt everything.
    ///
    /// Ground Stop is a file on disk rather than in-memory state, so it survives a Tower crash
    /// and can be set by hand when nothing else is responding.
    ///
    /// `POST /ground-stop`
    fn engage_ground_stop(
        &self,
    ) -> impl core::future::Future<Output = Result<GroundStop, Problem>> + Send;
    /// Resume.
    ///
    /// `DELETE /ground-stop`
    fn release_ground_stop(
        &self,
    ) -> impl core::future::Future<Output = Result<GroundStop, Problem>> + Send;
    /// Liveness, version and whether a Ground Stop is engaged.
    ///
    /// `GET /health`
    fn get_health(&self) -> impl core::future::Future<Output = Result<Health, Problem>> + Send;
    /// What agents are stuck on.
    ///
    /// A lights-out factory's worst failure is not a crash — a crash is loud. It is an agent that
    /// quietly cannot do what it was asked, produces something plausible anyway, and passes it
    /// downstream. This is the channel that stops that being invisible.
    ///
    /// Measured against a working prototype, five of six requests were permission or access
    /// failures, so `access` is worth filtering for first.
    ///
    /// `GET /help`
    fn list_help(
        &self,
        query: ListHelpQuery,
    ) -> impl core::future::Future<Output = Result<HelpList, Problem>> + Send;
    /// Mark help requests as dealt with.
    ///
    /// Resolving says *the blocker is gone*, not *I have read this*. An agent that raises the same
    /// problem on its next run will raise it again, which is the point: a list that clears itself
    /// on being looked at stops being evidence of anything.
    ///
    /// Narrow by agent, blocker or run. An empty body resolves every open request in the window,
    /// which is what you want after fixing something that stopped everything.
    ///
    /// `POST /help/resolve`
    fn resolve_help(
        &self,
        body: ResolveHelpRequest,
    ) -> impl core::future::Future<Output = Result<HelpResolved, Problem>> + Send;
    /// Chains of work, and what became of each.
    ///
    /// A run is one agent doing one thing; an itinerary is the whole causal chain and the budget
    /// it shares. The distinction matters most when something goes wrong: a chain can be *stalled*
    /// — every run in it succeeded and nothing will ever happen again — and a list of runs cannot
    /// show that, because there is no failed run to point at.
    ///
    /// `GET /itineraries`
    fn list_itineraries(
        &self,
        query: ListItinerariesQuery,
    ) -> impl core::future::Future<Output = Result<ItineraryList, Problem>> + Send;
    /// What agents have worked out, and how well established it is.
    ///
    /// A learning applies as soon as it is proposed and expires unless later runs arrive at it
    /// independently. There is no approval queue, deliberately: a sibling project built one and
    /// after 22 days held 88 learnings, none ever approved, so not one had ever reached a run.
    ///
    /// A learning becomes permanent through independent rediscovery, which is evidence, rather
    /// than through its `impact` rating, which is the agent's own claim about its own work.
    ///
    /// `GET /learnings`
    fn list_learnings(
        &self,
        query: ListLearningsQuery,
    ) -> impl core::future::Future<Output = Result<LearningList, Problem>> + Send;
    /// Settle a learning, either way.
    ///
    /// **This is not an approval queue.** A learning applies from the moment it is proposed, and
    /// nothing is waiting on you. A sibling project gated learnings behind approval and after 22
    /// days held 88 of them, none ever approved, so not one had ever reached a run.
    ///
    /// This is the override. `confirmed` means "this is real, keep it indefinitely" and spares it
    /// from lapsing. `rejected` means "this is wrong, stop applying it" and takes it out of every
    /// future run. Both are judgements a person makes about something already in use, not
    /// permission for it to start being used.
    ///
    /// `PATCH /learnings/{learning_id}`
    fn judge_learning(
        &self,
        path: JudgeLearningPath,
        body: JudgeLearningRequest,
    ) -> impl core::future::Future<Output = Result<Learning, Problem>> + Send;
    /// Every declared pipeline, its trigger and the flags it accepts.
    ///
    /// `GET /pipelines`
    fn list_pipelines(
        &self,
    ) -> impl core::future::Future<Output = Result<PipelineList, Problem>> + Send;
    /// Runs, live and historical.
    ///
    /// `GET /runs`
    fn list_runs(
        &self,
        query: ListRunsQuery,
    ) -> impl core::future::Future<Output = Result<RunList, Problem>> + Send;
    /// One run, including how it ended.
    ///
    /// `GET /runs/{run_id}`
    fn get_run(
        &self,
        path: GetRunPath,
    ) -> impl core::future::Future<Output = Result<Run, Problem>> + Send;
    /// What the agent wrote about this run.
    ///
    /// A transcript is not a report: it contains every approach the agent abandoned, and reading
    /// one to find out what happened is slower than doing the work again. This is the agent''s own
    /// account of what it concluded.
    ///
    /// `GET /runs/{run_id}/report`
    fn get_report(
        &self,
        path: GetReportPath,
    ) -> impl core::future::Future<Output = Result<Report, Problem>> + Send;
    /// Live output from a run, as server-sent events.
    ///
    /// `GET /runs/{run_id}/stream`
    fn stream_run(
        &self,
        path: StreamRunPath,
    ) -> impl core::future::Future<Output = Result<EventStream, Problem>> + Send;
}

/// Builds the axum router for this API.
///
/// Routes come straight from the specification, so a path can only exist here if it
/// exists there.
pub fn router<A: Api>(api: std::sync::Arc<A>) -> axum::Router {
    axum::Router::new()
        .route("/agents", axum::routing::get(handle_list_agents::<A>))
        .route("/costs", axum::routing::get(handle_get_costs::<A>))
        .route(
            "/flights",
            axum::routing::get(handle_list_pending::<A>).post(handle_send_flight::<A>),
        )
        .route(
            "/flights/{flight_id}",
            axum::routing::delete(handle_cancel_flight::<A>),
        )
        .route("/graph", axum::routing::get(handle_get_graph::<A>))
        .route(
            "/ground-stop",
            axum::routing::post(handle_engage_ground_stop::<A>)
                .delete(handle_release_ground_stop::<A>),
        )
        .route("/health", axum::routing::get(handle_get_health::<A>))
        .route("/help", axum::routing::get(handle_list_help::<A>))
        .route(
            "/help/resolve",
            axum::routing::post(handle_resolve_help::<A>),
        )
        .route(
            "/itineraries",
            axum::routing::get(handle_list_itineraries::<A>),
        )
        .route("/learnings", axum::routing::get(handle_list_learnings::<A>))
        .route(
            "/learnings/{learning_id}",
            axum::routing::patch(handle_judge_learning::<A>),
        )
        .route("/pipelines", axum::routing::get(handle_list_pipelines::<A>))
        .route("/runs", axum::routing::get(handle_list_runs::<A>))
        .route("/runs/{run_id}", axum::routing::get(handle_get_run::<A>))
        .route(
            "/runs/{run_id}/report",
            axum::routing::get(handle_get_report::<A>),
        )
        .route(
            "/runs/{run_id}/stream",
            axum::routing::get(handle_stream_run::<A>),
        )
        .with_state(api)
}

async fn handle_list_agents<A: Api>(
    axum::extract::State(api): axum::extract::State<std::sync::Arc<A>>,
) -> axum::response::Response {
    match api.list_agents().await {
        Ok(value) => (axum::http::StatusCode::OK, axum::Json(value)).into_response(),
        Err(problem) => problem.into_response(),
    }
}

async fn handle_get_costs<A: Api>(
    axum::extract::State(api): axum::extract::State<std::sync::Arc<A>>,
    axum::extract::Query(query): axum::extract::Query<GetCostsQuery>,
) -> axum::response::Response {
    match api.get_costs(query).await {
        Ok(value) => (axum::http::StatusCode::OK, axum::Json(value)).into_response(),
        Err(problem) => problem.into_response(),
    }
}

async fn handle_list_pending<A: Api>(
    axum::extract::State(api): axum::extract::State<std::sync::Arc<A>>,
) -> axum::response::Response {
    match api.list_pending().await {
        Ok(value) => (axum::http::StatusCode::OK, axum::Json(value)).into_response(),
        Err(problem) => problem.into_response(),
    }
}

async fn handle_send_flight<A: Api>(
    axum::extract::State(api): axum::extract::State<std::sync::Arc<A>>,
    axum::Json(body): axum::Json<SendFlightRequest>,
) -> axum::response::Response {
    match api.send_flight(body).await {
        Ok(value) => (axum::http::StatusCode::ACCEPTED, axum::Json(value)).into_response(),
        Err(problem) => problem.into_response(),
    }
}

async fn handle_cancel_flight<A: Api>(
    axum::extract::State(api): axum::extract::State<std::sync::Arc<A>>,
    axum::extract::Path(path): axum::extract::Path<CancelFlightPath>,
) -> axum::response::Response {
    match api.cancel_flight(path).await {
        Ok(value) => (axum::http::StatusCode::OK, axum::Json(value)).into_response(),
        Err(problem) => problem.into_response(),
    }
}

async fn handle_get_graph<A: Api>(
    axum::extract::State(api): axum::extract::State<std::sync::Arc<A>>,
    axum::extract::Query(query): axum::extract::Query<GetGraphQuery>,
) -> axum::response::Response {
    match api.get_graph(query).await {
        Ok(value) => (axum::http::StatusCode::OK, axum::Json(value)).into_response(),
        Err(problem) => problem.into_response(),
    }
}

async fn handle_engage_ground_stop<A: Api>(
    axum::extract::State(api): axum::extract::State<std::sync::Arc<A>>,
) -> axum::response::Response {
    match api.engage_ground_stop().await {
        Ok(value) => (axum::http::StatusCode::OK, axum::Json(value)).into_response(),
        Err(problem) => problem.into_response(),
    }
}

async fn handle_release_ground_stop<A: Api>(
    axum::extract::State(api): axum::extract::State<std::sync::Arc<A>>,
) -> axum::response::Response {
    match api.release_ground_stop().await {
        Ok(value) => (axum::http::StatusCode::OK, axum::Json(value)).into_response(),
        Err(problem) => problem.into_response(),
    }
}

async fn handle_get_health<A: Api>(
    axum::extract::State(api): axum::extract::State<std::sync::Arc<A>>,
) -> axum::response::Response {
    match api.get_health().await {
        Ok(value) => (axum::http::StatusCode::OK, axum::Json(value)).into_response(),
        Err(problem) => problem.into_response(),
    }
}

async fn handle_list_help<A: Api>(
    axum::extract::State(api): axum::extract::State<std::sync::Arc<A>>,
    axum::extract::Query(query): axum::extract::Query<ListHelpQuery>,
) -> axum::response::Response {
    match api.list_help(query).await {
        Ok(value) => (axum::http::StatusCode::OK, axum::Json(value)).into_response(),
        Err(problem) => problem.into_response(),
    }
}

async fn handle_resolve_help<A: Api>(
    axum::extract::State(api): axum::extract::State<std::sync::Arc<A>>,
    axum::Json(body): axum::Json<ResolveHelpRequest>,
) -> axum::response::Response {
    match api.resolve_help(body).await {
        Ok(value) => (axum::http::StatusCode::OK, axum::Json(value)).into_response(),
        Err(problem) => problem.into_response(),
    }
}

async fn handle_list_itineraries<A: Api>(
    axum::extract::State(api): axum::extract::State<std::sync::Arc<A>>,
    axum::extract::Query(query): axum::extract::Query<ListItinerariesQuery>,
) -> axum::response::Response {
    match api.list_itineraries(query).await {
        Ok(value) => (axum::http::StatusCode::OK, axum::Json(value)).into_response(),
        Err(problem) => problem.into_response(),
    }
}

async fn handle_list_learnings<A: Api>(
    axum::extract::State(api): axum::extract::State<std::sync::Arc<A>>,
    axum::extract::Query(query): axum::extract::Query<ListLearningsQuery>,
) -> axum::response::Response {
    match api.list_learnings(query).await {
        Ok(value) => (axum::http::StatusCode::OK, axum::Json(value)).into_response(),
        Err(problem) => problem.into_response(),
    }
}

async fn handle_judge_learning<A: Api>(
    axum::extract::State(api): axum::extract::State<std::sync::Arc<A>>,
    axum::extract::Path(path): axum::extract::Path<JudgeLearningPath>,
    axum::Json(body): axum::Json<JudgeLearningRequest>,
) -> axum::response::Response {
    match api.judge_learning(path, body).await {
        Ok(value) => (axum::http::StatusCode::OK, axum::Json(value)).into_response(),
        Err(problem) => problem.into_response(),
    }
}

async fn handle_list_pipelines<A: Api>(
    axum::extract::State(api): axum::extract::State<std::sync::Arc<A>>,
) -> axum::response::Response {
    match api.list_pipelines().await {
        Ok(value) => (axum::http::StatusCode::OK, axum::Json(value)).into_response(),
        Err(problem) => problem.into_response(),
    }
}

async fn handle_list_runs<A: Api>(
    axum::extract::State(api): axum::extract::State<std::sync::Arc<A>>,
    axum::extract::Query(query): axum::extract::Query<ListRunsQuery>,
) -> axum::response::Response {
    match api.list_runs(query).await {
        Ok(value) => (axum::http::StatusCode::OK, axum::Json(value)).into_response(),
        Err(problem) => problem.into_response(),
    }
}

async fn handle_get_run<A: Api>(
    axum::extract::State(api): axum::extract::State<std::sync::Arc<A>>,
    axum::extract::Path(path): axum::extract::Path<GetRunPath>,
) -> axum::response::Response {
    match api.get_run(path).await {
        Ok(value) => (axum::http::StatusCode::OK, axum::Json(value)).into_response(),
        Err(problem) => problem.into_response(),
    }
}

async fn handle_get_report<A: Api>(
    axum::extract::State(api): axum::extract::State<std::sync::Arc<A>>,
    axum::extract::Path(path): axum::extract::Path<GetReportPath>,
) -> axum::response::Response {
    match api.get_report(path).await {
        Ok(value) => (axum::http::StatusCode::OK, axum::Json(value)).into_response(),
        Err(problem) => problem.into_response(),
    }
}

async fn handle_stream_run<A: Api>(
    axum::extract::State(api): axum::extract::State<std::sync::Arc<A>>,
    axum::extract::Path(path): axum::extract::Path<StreamRunPath>,
) -> axum::response::Response {
    match api.stream_run(path).await {
        Ok(stream) => stream.into_response(),
        Err(problem) => problem.into_response(),
    }
}

/// Every operation the specification declares, as (method, path, operationId).
///
/// Exposed so tests can assert the router and the specification agree.
pub const OPERATIONS: [(&str, &str, &str); 19] = [
    ("GET", "/agents", "listAgents"),
    ("GET", "/costs", "getCosts"),
    ("GET", "/flights", "listPending"),
    ("POST", "/flights", "sendFlight"),
    ("DELETE", "/flights/{flight_id}", "cancelFlight"),
    ("GET", "/graph", "getGraph"),
    ("POST", "/ground-stop", "engageGroundStop"),
    ("DELETE", "/ground-stop", "releaseGroundStop"),
    ("GET", "/health", "getHealth"),
    ("GET", "/help", "listHelp"),
    ("POST", "/help/resolve", "resolveHelp"),
    ("GET", "/itineraries", "listItineraries"),
    ("GET", "/learnings", "listLearnings"),
    ("PATCH", "/learnings/{learning_id}", "judgeLearning"),
    ("GET", "/pipelines", "listPipelines"),
    ("GET", "/runs", "listRuns"),
    ("GET", "/runs/{run_id}", "getRun"),
    ("GET", "/runs/{run_id}/report", "getReport"),
    ("GET", "/runs/{run_id}/stream", "streamRun"),
];