refactor: complete Engine abstraction — move install, invocation, and paths behind Engine enum

.github/workflows/update-awf-version.md

@@ -29,7 +29,7 @@ There are four items to check:
 | Item | Upstream Source | Local Path |
 |------|---------------|------------|
 | `AWF_VERSION` | [github/gh-aw-firewall](https://github.com/github/gh-aw-firewall) latest release | `src/compile/common.rs` |
-| `COPILOT_CLI_VERSION` | [github/copilot-cli](https://github.com/github/copilot-cli) latest release | `src/compile/common.rs` |
+| `COPILOT_CLI_VERSION` | [github/copilot-cli](https://github.com/github/copilot-cli) latest release | `src/engine.rs` (re-exported in `src/compile/common.rs`) |
 | `MCPG_VERSION` | [github/gh-aw-mcpg](https://github.com/github/gh-aw-mcpg) latest release | `src/compile/common.rs` |
 | `ecosystem_domains.json` | [github/gh-aw](https://github.com/github/gh-aw) `pkg/workflow/data/ecosystem_domains.json` on `main` | `src/data/ecosystem_domains.json` |
 
@@ -45,7 +45,7 @@ Fetch the latest release of the upstream repository. Record the tag name, stripp
 
 ### Step 2: Read the Current Version
 
-Read the file `src/compile/common.rs` in this repository and find the corresponding constant:
+Read the file `src/compile/common.rs` (for `AWF_VERSION` and `MCPG_VERSION`) or `src/engine.rs` (for `COPILOT_CLI_VERSION`) in this repository and find the corresponding constant:
 
 - `pub const AWF_VERSION: &str = "...";`
 - `pub const COPILOT_CLI_VERSION: &str = "...";`
@@ -89,7 +89,7 @@ If the latest version is newer than the current constant:
   ```markdown
   ## Dependency Update
 
-  Updates the pinned `COPILOT_CLI_VERSION` constant in `src/compile/common.rs` from `<old-version>` to `<latest-version>`.
+  Updates the pinned `COPILOT_CLI_VERSION` constant in `src/engine.rs` from `<old-version>` to `<latest-version>`.
 
   ### Release
 

src/compile/common.rs

@@ -548,7 +548,11 @@ pub const AWF_VERSION: &str = "0.25.26";
 /// Version of the GitHub Copilot CLI (Microsoft.Copilot.CLI.linux-x64) NuGet package to install.
 /// Update this when upgrading to a new Copilot CLI release.
 /// See: https://pkgs.dev.azure.com/msazuresphere/_packaging/Guardian1ESPTUpstreamOrgFeed/nuget/v3/index.json
-pub const COPILOT_CLI_VERSION: &str = "1.0.34";
+///
+/// Re-exported from [`crate::engine::COPILOT_CLI_VERSION`] for backward compatibility.
+/// The canonical definition lives in `src/engine.rs`.
+#[allow(unused_imports)]
+pub use crate::engine::COPILOT_CLI_VERSION;
 
 /// Prefix used to identify agentic pipeline YAML files generated by ado-aw.
 pub const HEADER_MARKER: &str = "# @ado-aw";
@@ -1915,8 +1919,8 @@ pub async fn compile_shared(
         }
     }
 
-    // 4. Generate copilot params
-    let copilot_params = ctx.engine.args(ctx.front_matter, extensions)?;
+    // 4. Generate engine args
+    let engine_args = ctx.engine.args(ctx.front_matter, extensions)?;
 
     // 5. Compute workspace, working directory, triggers
     let effective_workspace = compute_effective_workspace(
@@ -2014,10 +2018,26 @@ pub async fn compile_shared(
     // 14. Shared replacements
     let compiler_version = env!("CARGO_PKG_VERSION");
     let integrity_check = generate_integrity_check(config.skip_integrity);
+
+    // Engine-generated pipeline fragments
+    let engine_install = ctx.engine.install_steps();
+    let engine_version = ctx.engine.version();
+    let engine_run = ctx.engine.invocation(&engine_args);
+    let engine_run_detection = ctx.engine.detection_invocation(&engine_args);
+    let engine_home_config_dir = ctx.engine.home_config_dir();
+    let engine_log_dir = ctx.engine.log_dir();
+    let engine_mcp_config_path = ctx.engine.mcp_config_path();
+
     let replacements: Vec<(&str, &str)> = vec![
         ("{{ parameters }}", &parameters_yaml),
         ("{{ compiler_version }}", compiler_version),
-        ("{{ copilot_version }}", COPILOT_CLI_VERSION),
+        ("{{ engine_version }}", engine_version),
+        ("{{ engine_install }}", &engine_install),
+        ("{{ engine_run }}", &engine_run),
+        ("{{ engine_run_detection }}", &engine_run_detection),
+        ("{{ engine_home_config_dir }}", engine_home_config_dir),
+        ("{{ engine_log_dir }}", engine_log_dir),
+        ("{{ engine_mcp_config_path }}", engine_mcp_config_path),
         ("{{ pool }}", &pool),
         ("{{ setup_job }}", &setup_job),
         ("{{ teardown_job }}", &teardown_job),
@@ -2035,7 +2055,6 @@ pub async fn compile_shared(
         ("{{ agent }}", &agent_name),
         ("{{ agent_name }}", &front_matter.name),
         ("{{ agent_description }}", &front_matter.description),
-        ("{{ copilot_params }}", &copilot_params),
         ("{{ source_path }}", &source_path),
         // integrity_check must come before pipeline_path because the
         // integrity step content itself contains {{ pipeline_path }}.
@@ -2156,10 +2175,10 @@ mod tests {
         assert!(result.is_ok());
     }
 
-    // ─── Engine::args (copilot params) ──────────────────────────────────────
+    // ─── Engine::args (engine args) ──────────────────────────────────────
 
     #[test]
-    fn test_copilot_params_bash_wildcard() {
+    fn test_engine_args_bash_wildcard() {
         let mut fm = minimal_front_matter();
         fm.tools = Some(crate::compile::types::ToolsConfig {
             bash: Some(vec![":*".to_string()]),
@@ -2173,7 +2192,7 @@ mod tests {
     }
 
     #[test]
-    fn test_copilot_params_bash_star_wildcard() {
+    fn test_engine_args_bash_star_wildcard() {
         let mut fm = minimal_front_matter();
         fm.tools = Some(crate::compile::types::ToolsConfig {
             bash: Some(vec!["*".to_string()]),
@@ -2187,7 +2206,7 @@ mod tests {
     }
 
     #[test]
-    fn test_copilot_params_bash_disabled() {
+    fn test_engine_args_bash_disabled() {
         let mut fm = minimal_front_matter();
         fm.tools = Some(crate::compile::types::ToolsConfig {
             bash: Some(vec![]),
@@ -2200,7 +2219,7 @@ mod tests {
     }
 
     #[test]
-    fn test_copilot_params_allow_all_paths_when_edit_enabled() {
+    fn test_engine_args_allow_all_paths_when_edit_enabled() {
         let fm = minimal_front_matter(); // edit defaults to true, bash defaults to wildcard
         let params = CompileContext::for_test(&fm).engine.args(&fm, &crate::compile::extensions::collect_extensions(&fm)).unwrap();
         assert!(params.contains("--allow-all-paths"), "edit enabled (default) should emit --allow-all-paths");
@@ -2209,7 +2228,7 @@ mod tests {
     }
 
     #[test]
-    fn test_copilot_params_no_allow_all_paths_when_edit_disabled() {
+    fn test_engine_args_no_allow_all_paths_when_edit_disabled() {
         let mut fm = minimal_front_matter();
         fm.tools = Some(crate::compile::types::ToolsConfig {
             bash: None,
@@ -2223,7 +2242,7 @@ mod tests {
     }
 
     #[test]
-    fn test_copilot_params_allow_all_tools_with_allow_all_paths() {
+    fn test_engine_args_allow_all_tools_with_allow_all_paths() {
         let mut fm = minimal_front_matter();
         fm.tools = Some(crate::compile::types::ToolsConfig {
             bash: Some(vec![":*".to_string()]),
@@ -2238,7 +2257,7 @@ mod tests {
     }
 
     #[test]
-    fn test_copilot_params_lean_adds_bash_commands() {
+    fn test_engine_args_lean_adds_bash_commands() {
         let mut fm = minimal_front_matter();
         fm.tools = Some(crate::compile::types::ToolsConfig {
             bash: Some(vec!["cat".to_string()]),
@@ -2258,7 +2277,7 @@ mod tests {
     }
 
     #[test]
-    fn test_copilot_params_lean_with_unrestricted_bash() {
+    fn test_engine_args_lean_with_unrestricted_bash() {
         let mut fm = minimal_front_matter();
         fm.tools = Some(crate::compile::types::ToolsConfig {
             bash: Some(vec![":*".to_string()]),
@@ -2276,7 +2295,7 @@ mod tests {
     }
 
     #[test]
-    fn test_copilot_params_custom_mcp_no_mcp_flag() {
+    fn test_engine_args_custom_mcp_no_mcp_flag() {
         let mut fm = minimal_front_matter();
         fm.mcp_servers.insert(
             "my-tool".to_string(),
@@ -2293,7 +2312,7 @@ mod tests {
     }
 
     #[test]
-    fn test_copilot_params_allow_tool_for_container_mcp() {
+    fn test_engine_args_allow_tool_for_container_mcp() {
         let mut fm = minimal_front_matter();
         fm.tools = Some(crate::compile::types::ToolsConfig {
             bash: Some(vec!["cat".to_string()]),
@@ -2313,7 +2332,7 @@ mod tests {
     }
 
     #[test]
-    fn test_copilot_params_allow_tool_for_url_mcp() {
+    fn test_engine_args_allow_tool_for_url_mcp() {
         let mut fm = minimal_front_matter();
         fm.tools = Some(crate::compile::types::ToolsConfig {
             bash: Some(vec!["cat".to_string()]),
@@ -2333,7 +2352,7 @@ mod tests {
     }
 
     #[test]
-    fn test_copilot_params_no_allow_tool_for_enabled_only_mcp() {
+    fn test_engine_args_no_allow_tool_for_enabled_only_mcp() {
         let mut fm = minimal_front_matter();
         fm.mcp_servers.insert(
             "my-tool".to_string(),
@@ -2344,7 +2363,7 @@ mod tests {
     }
 
     #[test]
-    fn test_copilot_params_allow_tool_mcps_sorted() {
+    fn test_engine_args_allow_tool_mcps_sorted() {
         let mut fm = minimal_front_matter();
         fm.tools = Some(crate::compile::types::ToolsConfig {
             bash: Some(vec!["cat".to_string()]),
@@ -2373,7 +2392,7 @@ mod tests {
     }
 
     #[test]
-    fn test_copilot_params_builtin_mcp_no_mcp_flag() {
+    fn test_engine_args_builtin_mcp_no_mcp_flag() {
         let mut fm = minimal_front_matter();
         fm.mcp_servers
             .insert("ado".to_string(), McpConfig::Enabled(true));
@@ -2383,7 +2402,7 @@ mod tests {
     }
 
     #[test]
-    fn test_copilot_params_max_turns_ignored() {
+    fn test_engine_args_max_turns_ignored() {
         let (fm, _) = parse_markdown(
             "---\nname: test\ndescription: test\nengine:\n  model: claude-opus-4.5\n  max-turns: 50\n---\n",
         )
@@ -2393,14 +2412,14 @@ mod tests {
     }
 
     #[test]
-    fn test_copilot_params_no_max_turns_when_simple_engine() {
+    fn test_engine_args_no_max_turns_when_simple_engine() {
         let fm = minimal_front_matter();
         let params = CompileContext::for_test(&fm).engine.args(&fm, &crate::compile::extensions::collect_extensions(&fm)).unwrap();
         assert!(!params.contains("--max-turns"));
     }
 
     #[test]
-    fn test_copilot_params_no_max_timeout() {
+    fn test_engine_args_no_max_timeout() {
         let (fm, _) = parse_markdown(
             "---\nname: test\ndescription: test\nengine:\n  model: claude-opus-4.5\n  timeout-minutes: 30\n---\n",
         )
@@ -2410,14 +2429,14 @@ mod tests {
     }
 
     #[test]
-    fn test_copilot_params_no_max_timeout_when_simple_engine() {
+    fn test_engine_args_no_max_timeout_when_simple_engine() {
         let fm = minimal_front_matter();
         let params = CompileContext::for_test(&fm).engine.args(&fm, &crate::compile::extensions::collect_extensions(&fm)).unwrap();
         assert!(!params.contains("--max-timeout"));
     }
 
     #[test]
-    fn test_copilot_params_max_turns_zero_not_emitted() {
+    fn test_engine_args_max_turns_zero_not_emitted() {
         let (fm, _) = parse_markdown(
             "---\nname: test\ndescription: test\nengine:\n  model: claude-opus-4.5\n  max-turns: 0\n---\n",
         )
@@ -2427,7 +2446,7 @@ mod tests {
     }
 
     #[test]
-    fn test_copilot_params_max_timeout_zero_not_emitted() {
+    fn test_engine_args_max_timeout_zero_not_emitted() {
         let (fm, _) = parse_markdown(
             "---\nname: test\ndescription: test\nengine:\n  model: claude-opus-4.5\n  timeout-minutes: 0\n---\n",
         )