From ef817ed5a06be1c3e0e067d1a59bf22241081d44 Mon Sep 17 00:00:00 2001 From: iris Date: Sun, 22 Nov 2026 13:40:34 +0100 Subject: [PATCH] swarm-controller: GET /api/models lists the model names the swarm already knows --- docs/4-implementation/swarm/inference.md | 6 ++ swarm-controller-api/src/inference.rs | 11 +++ swarm-controller/src/inference.rs | 120 ++++++++++++++++++++++- swarm-controller/src/startup.rs | 1 + 4 files changed, 136 insertions(+), 2 deletions(-) diff --git a/docs/4-implementation/swarm/inference.md b/docs/4-implementation/swarm/inference.md index c984ac78d..f757f8c7b 100644 --- a/docs/4-implementation/swarm/inference.md +++ b/docs/4-implementation/swarm/inference.md @@ -131,6 +131,12 @@ warning in its log, until the next `PUT` replaces it. | `PUT` | `/api/agents//inference` | the whole value, replacing the stored one; the controller refuses unknown fields, an unknown effort, or a model name with whitespace or a leading `-`, a `max_subagents` above 32, or a `soft_context_percent` outside 5 to 100 | | `DELETE` | `/api/agents//inference` | —; answers 204 | +`GET /api/models` answers `{"models": [...]}`: the distinct model names in +any agent's stored settings (its model and its subagent models) and in the +settings the agents reported running on, sorted. The swarm UI offers them in +the model dropdown, so no model name lives in the UI. A swarm where no agent +has either answers an empty list. + An agent's own queue credential grants it `$JS.API.DIRECT.GET.KV_agent-inference.$KV.agent-inference.`, the direct read of its own key, and nothing else in this bucket — the same shape diff --git a/swarm-controller-api/src/inference.rs b/swarm-controller-api/src/inference.rs index d1ec2502a..01cfd0430 100644 --- a/swarm-controller-api/src/inference.rs +++ b/swarm-controller-api/src/inference.rs @@ -51,6 +51,17 @@ pub struct InferenceSettings { pub fresh_session_percent: Option, } +/// What `GET /api/models` answers: the model names the swarm already knows, +/// for a form to offer. +#[derive(Debug, Serialize, Deserialize)] +#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))] +pub struct KnownModels { + /// Every distinct model in any agent's stored inference settings (its model + /// and its subagent models) or reported running, sorted. Empty on a swarm + /// where no agent has either. + pub models: Vec, +} + /// What `GET` answers for one agent. #[derive(Debug, Serialize, Deserialize)] #[cfg_attr(feature = "schema", derive(utoipa::ToSchema))] diff --git a/swarm-controller/src/inference.rs b/swarm-controller/src/inference.rs index df4d1d0ae..f42533f76 100644 --- a/swarm-controller/src/inference.rs +++ b/swarm-controller/src/inference.rs @@ -28,8 +28,8 @@ use axum::http::StatusCode; use futures_util::StreamExt as _; use problem_details::ProblemDetails; use swarm_controller_api::inference::{ - AgentInferenceView, EffectiveInference, InferenceSettings, MAX_SOFT_CONTEXT_PERCENT, - MAX_SUBAGENTS, MIN_SOFT_CONTEXT_PERCENT, + AgentInferenceView, EffectiveInference, InferenceSettings, KnownModels, + MAX_SOFT_CONTEXT_PERCENT, MAX_SUBAGENTS, MIN_SOFT_CONTEXT_PERCENT, }; use swarm_queue_client::agent_inference; use swarm_wire::agent_inference::{AgentInference, Effective}; @@ -202,6 +202,16 @@ impl Reported { } } + /// The models the agents reported running on. + fn models(&self) -> Vec { + self.latest + .lock() + .unwrap_or_else(PoisonError::into_inner) + .values() + .map(|e| e.model.clone()) + .collect() + } + fn get(&self, agent: &str) -> Option { self.latest .lock() @@ -267,6 +277,61 @@ pub(crate) async fn get_agent_inference( })) } +/// The distinct model names among `stored` settings and the `reported` ones, +/// sorted. +fn known_models<'a>( + stored: impl IntoIterator, + reported: Vec, +) -> Vec { + let mut models: BTreeSet = reported.into_iter().collect(); + for settings in stored { + models.extend(settings.model.iter().cloned()); + models.extend(settings.subagent_models.iter().flatten().cloned()); + } + models.into_iter().filter(|m| !m.is_empty()).collect() +} + +#[utoipa::path( + get, + path = "/api/models", + responses( + (status = 200, description = "the model names the swarm already knows: those in any \ + agent's stored inference settings and those the agents reported running on", + body = KnownModels), + (status = 503, description = "no swarm queue is configured on this host, or it is \ + not connected (problem+json)", body = String), + (status = 500, description = "the settings could not be read (problem+json)", + body = String), + ), + tag = "agents" +)] +pub(crate) async fn get_models( + State(state): State, +) -> Result, ProblemDetails> { + let client = queue(&state).map_err(refused)?; + let store = open(&client).await?; + let mut stored = Vec::new(); + let mut keys = store + .keys() + .await + .map_err(|e| queue_problem(&anyhow::Error::new(e)))?; + while let Some(key) = keys.next().await { + let key = key.map_err(|e| queue_problem(&anyhow::Error::new(e)))?; + let (current, _, _) = read_or_default::>(&store, &key) + .await + .map_err(|e| queue_problem(&e))?; + stored.extend(current); + } + let reported = state + .reported_inference + .as_ref() + .map(|r| r.models()) + .unwrap_or_default(); + Ok(Json(KnownModels { + models: known_models(&stored, reported), + })) +} + #[utoipa::path( put, path = "/api/agents/{name}/inference", @@ -562,6 +627,26 @@ mod tests { ); } + #[test] + fn known_models_merge_the_stored_and_the_reported_without_repeats() { + let stored = [ + into_stored( + settings(r#"{"model":"opus","subagent_models":["haiku","sonnet"]}"#).unwrap(), + ) + .unwrap(), + into_stored(settings(r#"{"effort":"high"}"#).unwrap()).unwrap(), + into_stored(settings(r#"{"model":"sonnet"}"#).unwrap()).unwrap(), + ]; + assert_eq!( + known_models( + &stored, + vec!["sonnet".to_owned(), "claude-opus-4-8".to_owned()] + ), + ["claude-opus-4-8", "haiku", "opus", "sonnet"] + ); + assert!(known_models(&[], Vec::new()).is_empty()); + } + #[test] fn bad_model_names_are_refused() { for json in [ @@ -703,6 +788,37 @@ mod tests { assert_eq!(&entry[..], b"{}"); } + /// The list reads every agent's key, counts an undecodable value as no + /// settings, and answers an empty list for an empty bucket. + #[tokio::test] + async fn the_models_list_reads_every_key_and_skips_an_undecodable_one() { + let nats = crate::test_nats::TestNats::start(); + let client = nats.client().await; + let state = crate::agent_limits::tests::declared(&client).await; + let store = agent_inference::open_or_create(&client) + .await + .expect("bucket"); + + let none = get_models(State(state.clone())).await.expect("read"); + assert!(none.0.models.is_empty()); + + for (agent, value) in [ + ( + "atlas", + &br#"{"model":"opus","subagent_models":["haiku"]}"#[..], + ), + ("iris", &br#"{"model":"sonnet"}"#[..]), + ("argus", &br#"{"effort":"later"}"#[..]), + ] { + store + .put(agent, value.to_vec().into()) + .await + .expect("written"); + } + let list = get_models(State(state)).await.expect("read"); + assert_eq!(list.0.models, ["haiku", "opus", "sonnet"]); + } + /// `restore` puts back the settings a `store` replaced, or takes the key /// out again when there was none. #[tokio::test] diff --git a/swarm-controller/src/startup.rs b/swarm-controller/src/startup.rs index 9941fc6de..566b2adc7 100644 --- a/swarm-controller/src/startup.rs +++ b/swarm-controller/src/startup.rs @@ -703,6 +703,7 @@ pub(crate) fn build_app(state: AppState) -> axum::Router { .routes(routes!(config_prs::get_agent_config_pr)) .routes(routes!(agents::get_agent_icon)) .routes(routes!(agents_md::get_agents_md, agents_md::put_agents_md)) + .routes(routes!(inference::get_models)) .routes(routes!( inference::get_agent_inference, inference::put_agent_inference,