feat(missions): Slice 5 — let a model size the mission's team
`routes/planner.rs` has had Opus proposing rosters since the Master Planner
shipped, and none of it ever reached a mission: the proposal lived in React state
and died with the tab. A mission's shape came from a team template instead —
fixed roles, and every claw minted `claude-sonnet-5` from a literal in
`mint_team_from_template`. That literal is why no mission has ever run more than
one provider.
A roster is `(topology_kind, [(role, backend)])`, which is exactly what the
composed executor already consumes: `Roster::graph` builds a `TopologyGraph` with
the backend in `attrs`, and `MicroVmTurnExecutor` reads `attrs["backend"]` per
node. So a verifier on another provider's rootfs stops being a bolt-on and
becomes a graph node — the correlated-failure break the independent judge exists
for, one layer down.
Three verbs, and the split is the point. **suggest** asks the model and persists
the answer, changing nothing. **decide** approves (writes `config.roster` and
switches the mission to the composed engine) or rejects. A proposal is never
applied on arrival: a model sizing a team is a suggestion about how many VMs to
boot, and this codebase treats model output that costs money as evidence for a
decision, not the decision.
Fail-closed at every seam, because each of these otherwise surfaces much later
and much more expensively:
- a backend no ONLINE node can boot is refused when PROPOSED, naming the ones
the fleet actually has. Placement would refuse it too — at launch, after the
roster was approved and someone believed the mission would run. The model is
handed that same list in its prompt, so the usual case never arises.
- an invented `topology_kind` is refused, not defaulted. `parse_topology_kind`
defaults to hub-spoke, which is right for a template we wrote and wrong for a
string a model just produced: running a `pipeline` proposal as a hub-and-spoke
changes what every node sees and nothing would say so.
- the roster is validated BEFORE it is stored, so a stored proposal is always
one that could be approved; and again at approval, against the fleet as it is
then — a node can go offline in between.
- `MAX_MEMBERS = 6`. Each member is a whole VM, not a subagent, and a model
asked to size a team proposes twelve happily.
Two properties live in SQL rather than in the handler: at most one approved
roster per mission (partial unique index — two approved rosters are two answers
to "what shape is this mission", and the executor reads one field), and
decide-once (`WHERE status = 'proposed'`, so a double-clicked approve claims
nothing the second time). Both tested against a real database, including that the
second approval is refused by Postgres rather than merely losing a race.
NEGATIVE CONTROL, run rather than assumed: with the roster preference removed
from `composed_graph`, `an_approved_roster_outranks_the_template` FAILS — 3 nodes
from the template instead of the roster's 2. A stored roster that is silently
ignored at launch is precisely the shape this project keeps paying for.
Not closed: per-role models for CLAWS. `template_roles` has no model column, so a
ZeroClaw team still mints one model for every role. The literal is now a named
constant that says so and points at the roster path, rather than sitting inline
where nobody reads it.
527 tests pass, clippy clean. Migration 0070. Not yet exercised against the
deployed stack — the route has never been called with a live model.
Co-Authored-By: Claude Opus 5 <[email protected]>
This commit is contained in:
Omar Sobh
co-authored by
Claude Opus 5
Claude Opus 5
parent
abb97e6f03
commit
1797669296
@@ -0,0 +1,349 @@
|
||||
//! A model-authored roster for a mission — Slice 5.
|
||||
//!
|
||||
//! The Master Planner has been proposing teams (2-6 members, a model each) since
|
||||
//! it shipped, and none of it reached a mission: the proposal lived in React
|
||||
//! state. A mission's shape came instead from a team template — fixed roles, and
|
||||
//! every claw minted `claude-sonnet-5`, which is why no mission has ever run
|
||||
//! heterogeneous providers.
|
||||
//!
|
||||
//! This is the seam. A roster is `(topology_kind, [(role, backend)])`, which is
|
||||
//! exactly what the composed executor consumes: `composed_graph` turns it into a
|
||||
//! `TopologyGraph`, and `MicroVmTurnExecutor` reads `attrs["backend"]` per node,
|
||||
//! so a `validator` role on a different provider's rootfs is a first-class graph
|
||||
//! node rather than a bolt-on.
|
||||
//!
|
||||
//! # Why the backend is validated here and not at boot
|
||||
//!
|
||||
//! Placement already refuses a mission whose backend no online node can run —
|
||||
//! but it refuses it at LAUNCH, after the roster was approved, the mission was
|
||||
//! created and someone believed it was going to run. A model that invents
|
||||
//! `rootfs-opus` is a normal thing for a model to do; discovering it three steps
|
||||
//! later is not. So a roster naming a backend the fleet cannot run is rejected
|
||||
//! when it is proposed, naming the backends that do exist.
|
||||
//!
|
||||
//! # What it deliberately does not do
|
||||
//!
|
||||
//! It does not mint claws. A composed mission's nodes are VMs, and provisioning
|
||||
//! containers for them would create agents and `.brain` files nothing ever
|
||||
//! dials — the same reason `on_launch` returns early for a microVM mission.
|
||||
|
||||
use serde::{Deserialize, Serialize};
|
||||
use uuid::Uuid;
|
||||
|
||||
/// One member of a proposed roster.
|
||||
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
|
||||
pub struct RosterMember {
|
||||
/// The node's role, e.g. `implementer`, `verifier`. Becomes the graph node's
|
||||
/// role, which is what the per-node prompt is written around.
|
||||
pub role: String,
|
||||
/// Which rootfs image this node's VM boots (`missions.backend` per node).
|
||||
/// `None` inherits the mission's.
|
||||
#[serde(default, skip_serializing_if = "Option::is_none")]
|
||||
pub backend: Option<String>,
|
||||
/// One line on why this member exists. Not consumed by anything — kept
|
||||
/// because a roster nobody can read is a roster nobody can refuse.
|
||||
#[serde(default, skip_serializing_if = "Option::is_none")]
|
||||
pub rationale: Option<String>,
|
||||
}
|
||||
|
||||
/// A proposed shape for a mission.
|
||||
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
|
||||
pub struct Roster {
|
||||
/// A `cm_topology::TopologyKind` name — `pipeline`, `hub_spoke`, …
|
||||
pub topology_kind: String,
|
||||
pub members: Vec<RosterMember>,
|
||||
}
|
||||
|
||||
/// Ceiling on a proposed roster.
|
||||
///
|
||||
/// Each member is a whole VM: a boot, an inject, an agent session and a collect.
|
||||
/// Anthropic's own guidance tops out at 3-5 subagents, and every member here
|
||||
/// costs far more than a subagent does. A model asked to size a team will
|
||||
/// cheerfully propose twelve.
|
||||
pub const MAX_MEMBERS: usize = 6;
|
||||
|
||||
/// Why a roster was refused.
|
||||
#[derive(Debug, Clone, PartialEq, Eq)]
|
||||
pub enum Refusal {
|
||||
Empty,
|
||||
TooMany(usize),
|
||||
BlankRole(usize),
|
||||
/// A backend no online node can run, with the ones that exist.
|
||||
UnknownBackend { backend: String, available: Vec<String> },
|
||||
UnknownTopology(String),
|
||||
}
|
||||
|
||||
impl std::fmt::Display for Refusal {
|
||||
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
|
||||
match self {
|
||||
Refusal::Empty => write!(f, "the roster has no members, so there is nothing to run"),
|
||||
Refusal::TooMany(n) => write!(
|
||||
f,
|
||||
"the roster has {n} members and the ceiling is {MAX_MEMBERS} — each one is a whole \
|
||||
VM, not a subagent"
|
||||
),
|
||||
Refusal::BlankRole(i) => write!(f, "member {i} has no role"),
|
||||
Refusal::UnknownBackend { backend, available } => write!(
|
||||
f,
|
||||
"no online node can run backend {backend:?}; the fleet has: {}",
|
||||
if available.is_empty() {
|
||||
"(none — no node reports a microvm rootfs)".to_string()
|
||||
} else {
|
||||
available.join(", ")
|
||||
}
|
||||
),
|
||||
Refusal::UnknownTopology(k) => write!(
|
||||
f,
|
||||
"{k:?} is not a topology kind this platform can plan; use one of: {}",
|
||||
cm_topology::TopologyKind::ALL
|
||||
.iter()
|
||||
.map(|k| k.as_str())
|
||||
.collect::<Vec<_>>()
|
||||
.join(", ")
|
||||
),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl Roster {
|
||||
/// Check a roster against the platform and the fleet.
|
||||
///
|
||||
/// `available` is the set of backends at least one ONLINE node can boot.
|
||||
/// Fail-closed on every axis: an unrecognised topology, a blank role and an
|
||||
/// unbuildable backend are all refusals, because each of them becomes a
|
||||
/// failure much later and much more expensively.
|
||||
pub fn validate(&self, available: &[String]) -> Result<(), Refusal> {
|
||||
if self.members.is_empty() {
|
||||
return Err(Refusal::Empty);
|
||||
}
|
||||
if self.members.len() > MAX_MEMBERS {
|
||||
return Err(Refusal::TooMany(self.members.len()));
|
||||
}
|
||||
if parse_kind(&self.topology_kind).is_none() {
|
||||
return Err(Refusal::UnknownTopology(self.topology_kind.clone()));
|
||||
}
|
||||
for (i, m) in self.members.iter().enumerate() {
|
||||
if m.role.trim().is_empty() {
|
||||
return Err(Refusal::BlankRole(i));
|
||||
}
|
||||
if let Some(b) = m.backend.as_deref().map(str::trim).filter(|b| !b.is_empty()) {
|
||||
if !available.iter().any(|a| a == b) {
|
||||
return Err(Refusal::UnknownBackend {
|
||||
backend: b.to_string(),
|
||||
available: available.to_vec(),
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// The graph a composed run executes.
|
||||
///
|
||||
/// Node ids follow `cm_topology::build`'s `n0..` convention so the graph is
|
||||
/// indistinguishable from a template-built one — the executor, the planners
|
||||
/// and the checkpoint all treat it the same. The per-member backend rides in
|
||||
/// `attrs`, which is the channel `MicroVmTurnExecutor` already reads.
|
||||
pub fn graph(&self) -> Result<serde_json::Value, String> {
|
||||
let kind = parse_kind(&self.topology_kind)
|
||||
.ok_or_else(|| format!("unknown topology kind {:?}", self.topology_kind))?;
|
||||
let roles: Vec<&str> = self.members.iter().map(|m| m.role.trim()).collect();
|
||||
let mut graph =
|
||||
cm_topology::build(kind, &roles).map_err(|e| format!("build topology: {e}"))?;
|
||||
for (node, member) in graph.nodes.iter_mut().zip(self.members.iter()) {
|
||||
if let Some(b) = member
|
||||
.backend
|
||||
.as_deref()
|
||||
.map(str::trim)
|
||||
.filter(|b| !b.is_empty())
|
||||
{
|
||||
node.attrs.insert("backend".to_string(), b.to_string());
|
||||
}
|
||||
}
|
||||
serde_json::to_value(&graph).map_err(|e| format!("serialize graph: {e}"))
|
||||
}
|
||||
}
|
||||
|
||||
/// Topology kind by name, accepting exactly what the catalog declares.
|
||||
///
|
||||
/// Deliberately not `unwrap_or(HubSpoke)`. `mission_orchestrator::
|
||||
/// parse_topology_kind` does default, which is right for a stored template
|
||||
/// written by us and wrong for a string a model just invented: silently running
|
||||
/// a `pipeline` proposal as a hub-and-spoke would change what every node sees
|
||||
/// and nothing would say so.
|
||||
fn parse_kind(s: &str) -> Option<cm_topology::TopologyKind> {
|
||||
let want = s.trim();
|
||||
cm_topology::TopologyKind::ALL
|
||||
.iter()
|
||||
.copied()
|
||||
.find(|k| k.as_str().eq_ignore_ascii_case(want))
|
||||
}
|
||||
|
||||
/// Backends at least one online node can actually boot.
|
||||
///
|
||||
/// Read from the nodes' reported `rootfs` capability, so it answers "what can
|
||||
/// run today" rather than "what images did someone build once".
|
||||
pub async fn available_backends(
|
||||
pool: &sqlx::PgPool,
|
||||
workspace_id: Uuid,
|
||||
) -> Result<Vec<String>, String> {
|
||||
let rows: Vec<(serde_json::Value,)> = sqlx::query_as(
|
||||
"SELECT capabilities -> 'rootfs'
|
||||
FROM nodes
|
||||
WHERE workspace_id = $1 AND status = 'online'
|
||||
AND capabilities @> '{\"microvm\": true}'::jsonb",
|
||||
)
|
||||
.bind(workspace_id)
|
||||
.fetch_all(pool)
|
||||
.await
|
||||
.map_err(|e| format!("read node rootfs capabilities: {e}"))?;
|
||||
|
||||
let mut out: Vec<String> = rows
|
||||
.into_iter()
|
||||
.filter_map(|(v,)| v.as_array().cloned())
|
||||
.flatten()
|
||||
.filter_map(|v| v.as_str().map(str::to_string))
|
||||
.collect();
|
||||
out.sort();
|
||||
out.dedup();
|
||||
Ok(out)
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
fn member(role: &str, backend: Option<&str>) -> RosterMember {
|
||||
RosterMember {
|
||||
role: role.into(),
|
||||
backend: backend.map(str::to_string),
|
||||
rationale: None,
|
||||
}
|
||||
}
|
||||
|
||||
fn roster(kind: &str, members: Vec<RosterMember>) -> Roster {
|
||||
Roster {
|
||||
topology_kind: kind.into(),
|
||||
members,
|
||||
}
|
||||
}
|
||||
|
||||
/// A backend the fleet cannot boot must be refused where it is PROPOSED.
|
||||
/// Placement would refuse it too — at launch, after the roster was approved
|
||||
/// and someone believed the mission was going to run.
|
||||
#[test]
|
||||
fn a_backend_no_node_can_run_is_refused_with_the_ones_that_exist() {
|
||||
let have = vec!["claude".to_string(), "kimi".to_string()];
|
||||
let r = roster(
|
||||
"pipeline",
|
||||
vec![member("implementer", Some("claude")), member("verifier", Some("rootfs-opus"))],
|
||||
);
|
||||
let err = r.validate(&have).unwrap_err();
|
||||
assert_eq!(
|
||||
err,
|
||||
Refusal::UnknownBackend {
|
||||
backend: "rootfs-opus".into(),
|
||||
available: have.clone()
|
||||
}
|
||||
);
|
||||
// The message must name what IS available, or the operator's next move
|
||||
// is a guess.
|
||||
let msg = err.to_string();
|
||||
assert!(msg.contains("claude") && msg.contains("kimi"), "{msg}");
|
||||
|
||||
// And the same roster passes once every backend is one the fleet has.
|
||||
let ok = roster(
|
||||
"pipeline",
|
||||
vec![member("implementer", Some("claude")), member("verifier", Some("kimi"))],
|
||||
);
|
||||
assert!(ok.validate(&have).is_ok());
|
||||
}
|
||||
|
||||
/// A member with no backend inherits the mission's, which is legitimate —
|
||||
/// the whole roster does not have to be heterogeneous to be useful.
|
||||
#[test]
|
||||
fn a_member_without_a_backend_is_not_a_refusal() {
|
||||
let r = roster("pipeline", vec![member("implementer", None)]);
|
||||
assert!(r.validate(&["claude".to_string()]).is_ok());
|
||||
// Blank counts as absent, not as a backend named "".
|
||||
let r = roster("pipeline", vec![member("implementer", Some(" "))]);
|
||||
assert!(r.validate(&["claude".to_string()]).is_ok());
|
||||
}
|
||||
|
||||
/// The ceiling. Each member is a VM boot, an inject, a full agent session
|
||||
/// and a collect — a model asked to size a team proposes twelve happily.
|
||||
#[test]
|
||||
fn a_roster_is_bounded_and_non_empty() {
|
||||
let have = vec!["claude".to_string()];
|
||||
assert_eq!(roster("pipeline", vec![]).validate(&have), Err(Refusal::Empty));
|
||||
|
||||
let many: Vec<_> = (0..MAX_MEMBERS + 1)
|
||||
.map(|i| member(&format!("r{i}"), None))
|
||||
.collect();
|
||||
assert_eq!(
|
||||
roster("pipeline", many).validate(&have),
|
||||
Err(Refusal::TooMany(MAX_MEMBERS + 1))
|
||||
);
|
||||
|
||||
let exactly: Vec<_> = (0..MAX_MEMBERS).map(|i| member(&format!("r{i}"), None)).collect();
|
||||
assert!(roster("pipeline", exactly).validate(&have).is_ok());
|
||||
}
|
||||
|
||||
/// An invented topology kind must be refused, NOT defaulted. Running a
|
||||
/// `pipeline` proposal as a hub-and-spoke changes what every node sees and
|
||||
/// nothing would say so — the same silent-substitution shape as a backend
|
||||
/// that quietly falls back to the default image.
|
||||
#[test]
|
||||
fn an_invented_topology_kind_is_refused_rather_than_defaulted() {
|
||||
let have = vec!["claude".to_string()];
|
||||
let r = roster("assembly_line", vec![member("implementer", None)]);
|
||||
assert_eq!(
|
||||
r.validate(&have),
|
||||
Err(Refusal::UnknownTopology("assembly_line".into()))
|
||||
);
|
||||
// Every kind the catalog declares is accepted, so this cannot drift out
|
||||
// of sync with what the orchestrator can actually plan.
|
||||
for kind in cm_topology::TopologyKind::ALL {
|
||||
let r = roster(kind.as_str(), vec![member("implementer", None)]);
|
||||
assert!(r.validate(&have).is_ok(), "{}", kind.as_str());
|
||||
}
|
||||
}
|
||||
|
||||
/// The graph is the handoff to the composed executor: node ids in
|
||||
/// `cm_topology`'s own convention, and the backend in the `attrs` channel
|
||||
/// `MicroVmTurnExecutor` reads. If this drifts, a heterogeneous roster runs
|
||||
/// every node on the mission default and looks fine.
|
||||
#[test]
|
||||
fn the_graph_carries_each_members_backend_where_the_executor_reads_it() {
|
||||
let r = roster(
|
||||
"pipeline",
|
||||
vec![
|
||||
member("implementer", Some("claude")),
|
||||
member("verifier", Some("kimi")),
|
||||
member("scribe", None),
|
||||
],
|
||||
);
|
||||
let g = r.graph().expect("a runnable graph");
|
||||
let nodes = g["nodes"].as_array().expect("nodes");
|
||||
assert_eq!(nodes.len(), 3);
|
||||
assert_eq!(nodes[0]["role"], "implementer");
|
||||
assert_eq!(nodes[0]["attrs"]["backend"], "claude");
|
||||
assert_eq!(nodes[1]["attrs"]["backend"], "kimi");
|
||||
assert!(
|
||||
nodes[2]["attrs"].get("backend").is_none(),
|
||||
"a member with no backend must inherit the mission's, not be stamped with one"
|
||||
);
|
||||
|
||||
// And it deserializes as the real thing the worker will parse — a graph
|
||||
// that only looks right as JSON fails at claim time with "missing or
|
||||
// invalid graph", which reads as a runtime fault rather than a bad
|
||||
// roster.
|
||||
let parsed: cm_topology::TopologyGraph =
|
||||
serde_json::from_value(g).expect("the worker must be able to parse it");
|
||||
assert_eq!(parsed.nodes.len(), 3);
|
||||
assert_eq!(
|
||||
parsed.nodes[1].attrs.get("backend").map(String::as_str),
|
||||
Some("kimi")
|
||||
);
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user