feat(cli): expose advisory capacity through stack and MCP

Author: HaoZeke

src/main.rs

@@ -1180,6 +1180,40 @@ struct BatchArgs {
     out_dir: PathBuf,
 }
 
+#[derive(clap::Args, Debug)]
+struct CapacityArgs {
+    /// Captured normalized capacity snapshot; no scheduler calls are made.
+    #[arg(long)]
+    snapshot: PathBuf,
+    /// Exact partition whose inventory must be complete.
+    #[arg(long)]
+    partition: String,
+    /// Physical host target, independent of the compiler target.
+    #[arg(long = "target")]
+    host_target: String,
+    /// Literal required feature; repeated features are combined with AND.
+    #[arg(long = "feature")]
+    features: Vec<String>,
+    /// CPUs required on one node.
+    #[arg(long)]
+    cpus: u64,
+    /// Scheduler memory required on one node, in MiB.
+    #[arg(long)]
+    memory_mib: u64,
+    /// GPUs required on one node.
+    #[arg(long, default_value_t = 0)]
+    gpus: u64,
+    /// Required GPU type.
+    #[arg(long)]
+    gpu_type: Option<String>,
+    /// RFC3339 evaluation time for deterministic replay; absent is now.
+    #[arg(long)]
+    generated_at: Option<String>,
+    /// Maximum age of the observation, in seconds.
+    #[arg(long, default_value_t = 300)]
+    max_age_seconds: u64,
+}
+
 #[derive(clap::Args, Debug)]
 struct ShardArgs {
     /// Jenkins build list of one node type: `Name-version-toolchain.eb
@@ -1648,6 +1682,8 @@ enum StackCommand {
         after_long_help = "Examples:\n  eb-stack stack shard --build-list rome.list --easyconfigs easybuild-easyconfigs/easybuild/easyconfigs --easyconfigs site-easyconfigs --installed-modules-dir /cvmfs/software.eessi.io/versions/2026.06/software/linux/x86_64/amd/zen2/modules/all --installed-modules-dir site-modules/all --shards 4 --weights build-seconds.tsv --out-dir shards\n  eb-stack stack shard --build-list rome.list --easyconfigs easybuild-easyconfigs/easybuild/easyconfigs --commit-cache /scratch-shared/$USER/eb-stack-commit-trees --shards 4 --out-dir shards\n  eb-stack stack shard --build-list rome.list --easyconfigs easybuild-easyconfigs/easybuild/easyconfigs --easyconfigs-repo easybuild-easyconfigs --materialize --build-robot-path /sw/easybuild/easyconfigs --shards 4 --out-dir shards"
     )]
     Shard(Box<ShardArgs>),
+    /// Inspect timestamped advisory scheduler capacity without placing jobs.
+    Capacity(Box<CapacityArgs>),
     /// Write the peak build-tree inode footprint per software name.
     ///
     /// The peak of `build.inodes_peak` over the records of each `--ledger`,
@@ -3592,6 +3628,30 @@ fn run_stack(command: StackCommand) -> Result<()> {
             println!("{}", run.summary());
             Ok(())
         }
+        StackCommand::Capacity(args) => {
+            let bytes = std::fs::read(&args.snapshot)
+                .with_context(|| format!("--snapshot {}: not readable", args.snapshot.display()))?;
+            let evaluated_at = args
+                .generated_at
+                .unwrap_or_else(|| chrono::Utc::now().to_rfc3339());
+            let request = eb_stack::planning_capacity::CapacityRequest {
+                partition: args.partition,
+                host_target: args.host_target,
+                features: args.features.into_iter().collect(),
+                cpus: args.cpus,
+                memory_mib: args.memory_mib,
+                gpus: args.gpus,
+                gpu_type: args.gpu_type,
+            };
+            let report = eb_stack::planning_capacity::inspect(
+                &bytes,
+                &request,
+                &evaluated_at,
+                args.max_age_seconds,
+            )?;
+            println!("{}", serde_json::to_string_pretty(&report)?);
+            Ok(())
+        }
         StackCommand::Shard(args) => {
             let ShardArgs {
                 build_list,

src/mcp.rs

@@ -457,6 +457,12 @@ fn tool_catalog() -> Vec<Value> {
                 ("oom_resources", "string"),
             ],
         ),
+        tool_with_optional(
+            "eb_stack_capacity",
+            "Report timestamped advisory scheduler capacity from a normalized snapshot, as stack capacity does. Partition, physical host target and literal AND features stay exact. Reports per-node resource fits without node names, queue-wait predictions, placement guarantees or admission changes. Missing partition/pending observations remain unknown.",
+            &[("snapshot","string"),("partition","string"),("target","string"),("cpus","integer"),("memory_mib","integer")],
+            &[("feature","array"),("gpus","integer"),("gpu_type","string"),("generated_at","string"),("max_age_seconds","integer")],
+        ),
         tool_with_optional(
             "eb_stack_shard",
             "Split one Jenkins build list into shards that can build at the same time, as `stack shard` does. Each line's closure is computed over easyconfigs minus the modules in installed lists and installed_modules_dir Lmod trees. Lines whose own easyconfig another line needs share a shard; any other module two or more shards need goes to prelude.list. Groups are packed into at most shards shards by weight (weights TSV, else default_weight). Writes prelude.list, shard-NN.list (input lines verbatim) and plan.json to out_dir. A line with --from-commit or --from-pr takes the easyconfig it names from that tree, and its dependencies from easyconfigs first and that tree second, as EasyBuild appends the fetched files to its robot path. Trees come from commit_tree (COMMIT=DIR), easyconfigs_repo (a git repository whose objects hold the commits, read in place), pr_tree (N=DIR), or commit_cache, a directory a missing tree is downloaded into from GitHub; a prelude module only such a tree provides keeps the line's source options. With materialize, also writes sources/v1/<commit>/ (the files the plan reads from each commit, with a SHA-256 manifest) and prelude.local.list and shard-NN.local.list, whose --from-commit lines read that directory through --robot-paths set to build_robot_path (the build host's robot paths, in EasyBuild's order) and then the directory; a line that cannot run that way is copied unchanged. A fetched line that still cannot be resolved, or an easyconfig that does not parse, is planned on its own and listed under warnings. Any other line that cannot be resolved is a tool error and nothing is written.",
@@ -934,6 +940,7 @@ fn call_tool(name: &str, arguments: &Value) -> Result<Value, String> {
         "eb_stack_shadow" => stack_shadow_tool(arguments),
         "eb_stack_batch" => stack_batch_tool(arguments),
         "eb_stack_shard" => stack_shard_tool(arguments),
+        "eb_stack_capacity" => stack_capacity_tool(arguments),
         "eb_stack_footprints" => stack_footprints_tool(arguments),
         "eb_stack_admit" => stack_admit_tool(arguments),
         "eb_stack_arch" => stack_arch_tool(arguments),
@@ -3279,6 +3286,31 @@ fn stack_provided_tool(arguments: &Value) -> Result<Value, String> {
     }))
 }
 
+fn stack_capacity_tool(arguments: &Value) -> Result<Value, String> {
+    let path = required_path(arguments, "snapshot")?;
+    let bytes =
+        std::fs::read(&path).map_err(|error| format!("snapshot {}: {error}", path.display()))?;
+    let request = crate::planning_capacity::CapacityRequest {
+        partition: required_string(arguments, "partition")?,
+        host_target: required_string(arguments, "target")?,
+        features: string_array(arguments, "feature")?.into_iter().collect(),
+        cpus: optional_u64(arguments, "cpus")?.ok_or("cpus is required")?,
+        memory_mib: optional_u64(arguments, "memory_mib")?.ok_or("memory_mib is required")?,
+        gpus: optional_u64(arguments, "gpus")?.unwrap_or(0),
+        gpu_type: optional_string(arguments, "gpu_type"),
+    };
+    let evaluated_at =
+        crate::site_commands::generated_at(optional_string(arguments, "generated_at"), false)
+            .map_err(workflow_error)?;
+    crate::planning_capacity::inspect(
+        &bytes,
+        &request,
+        &evaluated_at,
+        optional_u64(arguments, "max_age_seconds")?.unwrap_or(300),
+    )
+    .map_err(workflow_error)
+}
+
 fn stack_shard_tool(arguments: &Value) -> Result<Value, String> {
     let shards = optional_u64(arguments, "shards")?.ok_or("shards is required")?;
     let request = crate::site_commands::StackShardRequest {

tests/planning_capacity.rs

@@ -59,6 +59,7 @@ fn mixed_resources_are_subtracted_and_unavailable_states_are_excluded() {
     assert_eq!(result["pending"]["status"], "unknown");
     assert!(result["pending"]["known_demand"].is_null());
     assert!(!result.to_string().contains("example-gpu-private-host"));
+    assert!(!result.to_string().contains("\"name\":"));
 }
 
 #[test]