Abstract engine

[jamesadevine]

/plan We only support one engine: copilot. There are a lot of copilot specific hooks across the code base. In the future we may add new engines, but the codebase is quite messy with github_copilot specific functions all across the place. Let's plan an Engine trait and implementation for github copilot CLI. The goal is to consolidate disparate functions into a single location

[github-actions]

✅ Issue Plan Maker completed successfully!

[github-actions]

Engine Abstraction Plan

Objective

Consolidate all GitHub Copilot CLI–specific logic into a single Engine trait + CopilotCliEngine implementation, so that the rest of the compiler treats the agent runner as a pluggable component rather than hard-coding copilot assumptions throughout.

---

Current state — Copilot-specific code locations

Location	What's copilot-specific
src/compile/common.rs	generate_copilot_params(), COPILOT_CLI_VERSION const, generate_copilot_ado_env(), template replacements {{ copilot_params }}, {{ copilot_version }}, {{ copilot_ado_env }}
src/compile/extensions.rs	allowed_copilot_tools() method on CompilerExtension trait and extension_enum! macro delegate
src/data/base.yml + 1es-base.yml	NuGet install steps for Microsoft.Copilot.CLI.linux-x64, binary copy, copilot --version, AWF command (/tmp/awf-tools/copilot ...), {{ copilot_*}} markers
src/run.rs	Direct copilot binary invocation, generate_copilot_params() call, debug log messages

---

Scope

In scope

• Define an Engine trait in a new src/engine/ module
• Implement CopilotCliEngine that moves all the Copilot-specific logic out of common.rs and run.rs
• Rename allowed_copilot_tools() → allowed_engine_tools() on CompilerExtension (cosmetic, removes copilot assumption from the extension interface)
• Rename template markers from {{ copilot_* }} to engine-neutral names ({{ engine_params }}, {{ engine_version }}, {{ agent_env }}) in both templates and compiler

Out of scope

• Implementing any second engine
• Changing the engine: front matter syntax (that's already engine-neutral)
• Changes to safe outputs, MCPG, AWF, or execution (Stage 3)

---

Work breakdown

• 1. Create src/engine/mod.rs — define the Engine trait:

  pub trait Engine: Send + Sync {
      fn name(&self) -> &str;
      fn version(&self) -> &str;
      fn binary_name(&self) -> &str;
      fn cli_params(&self, fm: &FrontMatter, extensions: &[Extension]) -> Result<String>;
      fn agent_ado_env(&self, read_sc: Option<&str>) -> String;
      fn install_steps(&self) -> String;    // YAML string for pipeline template
      fn template_replacements(&self, fm: &FrontMatter, extensions: &[Extension]) -> Result<Vec<(String, String)>>;
  }
  pub fn default_engine() -> Box<dyn Engine> { Box::new(copilot::CopilotCliEngine) }

• 2. Create src/engine/copilot.rs — CopilotCliEngine struct:

  • Move COPILOT_CLI_VERSION const here
  • Move generate_copilot_params() → CopilotCliEngine::cli_params()
  • Move generate_copilot_ado_env() → CopilotCliEngine::agent_ado_env()
  • Implement install_steps() to return the NuGet install + path setup YAML block (currently hardcoded in both templates)

• 3. Rename allowed_copilot_tools() → allowed_engine_tools() on CompilerExtension trait:

  • Update trait definition in src/compile/extensions.rs
  • Update extension_enum! macro delegate
  • Update all 3 call sites: AzureDevOpsExtension, GitHubExtension, SafeOutputsExtension
  • Update the call in generate_copilot_params() (to be moved in step 2)

• 4. Rename template markers in src/data/base.yml and src/data/1es-base.yml:

  • {{ copilot_params }} → {{ engine_params }}
  • {{ copilot_version }} → {{ engine_version }}
  • {{ copilot_ado_env }} → {{ agent_env }}
  • Update corresponding replacements in compile_pipeline() in common.rs

• 5. Update compile_pipeline() in src/compile/common.rs:

  • Accept an &dyn Engine parameter (or call default_engine() internally)
  • Replace generate_copilot_params() call with engine.cli_params()
  • Replace generate_copilot_ado_env() call with engine.agent_ado_env()
  • Populate template replacements from engine.template_replacements()
  • Remove the now-moved functions and constant from common.rs

• 6. Update src/run.rs:

  • Replace direct copilot string with engine.binary_name()
  • Replace compile::generate_copilot_params() call with engine.cli_params()
  • Obtain engine via engine::default_engine()

• 7. Update src/main.rs:

  • Register the new engine module
  • No CLI changes needed

---

Validation strategy

• cargo test — all existing unit tests for generate_copilot_params (now in CopilotCliEngine::cli_params) must continue to pass; they live in src/compile/common.rs and can stay there as integration-level tests or move to src/engine/copilot.rs
• cargo clippy — no new warnings
• Integration: cargo run -- compile examples/*.md — spot-check that generated YAML still contains the correct install/invocation steps (the template marker rename is the highest-risk change here; a single grep for leftover {{ copilot_ in compiled output would confirm it)
• The check subcommand (cargo run -- check <compiled.yml>) against a freshly compiled pipeline should still pass

---

Risks and mitigations

Risk	Mitigation
Template marker rename ({{ copilot_params }} → {{ engine_params }}) breaks compiled YAMLs already in repos	This is a compile-time change only — existing compiled YAMLs are already concrete YAML. Operators must recompile (which is already required whenever ado-aw updates).
install_steps() returning a raw YAML string is fragile	Alternative: keep install steps in the template but behind a new {{ engine_install }} marker that CopilotCliEngine fills — cleaner than string surgery
Box<dyn Engine> adds a heap allocation per compile run	Negligible; can use enum Engine { CopilotCli(CopilotCliEngine) } for zero-cost static dispatch if preferred
Test suite tests generate_copilot_params by name	Move tests alongside the impl, or keep them as common::tests calling through the new path — either works

---

Dependencies and assumptions

• No second engine is needed to validate the abstraction — the trait just needs to compile cleanly with one implementation
• The front matter engine: { model: ... } field is already engine-neutral and does not need changes
• Template markers can be freely renamed since base.yml and 1es-base.yml are compiled-in data files (include_str!), not shipped separately

Generated by Issue Plan Maker for issue #280 · ● 873.6K · ◷