Skip to content

Refactor CodingAgentEngine using Interface Segregation Principle #11607

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pelikhan merged 3 commits into from
Jan 24, 2026
Merged

Refactor CodingAgentEngine using Interface Segregation Principle #11607

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d5702e0
Initial plan
Copilot Jan 24, 2026
c2bfe60
Refactor CodingAgentEngine interface using Interface Segregation Prin…
Copilot Jan 24, 2026
80717c1
Fix linter issues in interface segregation tests
Copilot Jan 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
110 changes: 108 additions & 2 deletions pkg/workflow/agentic_engine.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,82 @@ var agenticEngineLog = logger.New("workflow:agentic_engine")
// GitHubActionStep represents the YAML lines for a single step in a GitHub Actions workflow
type GitHubActionStep []string

// CodingAgentEngine represents an AI coding agent that can be used as an engine to execute agentic workflows
type CodingAgentEngine interface {
// Interface Segregation Architecture
//
// The agentic engine interfaces follow the Interface Segregation Principle (ISP) to avoid
// forcing implementations to depend on methods they don't use. The architecture uses interface
// composition to provide flexibility while maintaining backward compatibility.
//
// Core Principles:
// 1. Focused interfaces with single responsibilities
// 2. Composition over monolithic interfaces
// 3. Backward compatibility via composite interface
// 4. Optional capabilities via interface type assertions
//
// Interface Hierarchy:
//
// Engine (core identity - required by all)
// ├── GetID()
// ├── GetDisplayName()
// ├── GetDescription()
// └── IsExperimental()
//
// CapabilityProvider (feature detection - optional)
// ├── SupportsToolsAllowlist()
// ├── SupportsHTTPTransport()
// ├── SupportsMaxTurns()
// ├── SupportsWebFetch()
// ├── SupportsWebSearch()
// └── SupportsFirewall()
//
// WorkflowExecutor (compilation - required)
// ├── GetDeclaredOutputFiles()
// ├── GetInstallationSteps()
// └── GetExecutionSteps()
//
// MCPConfigProvider (MCP servers - optional)
// └── RenderMCPConfig()
//
// LogParser (log analysis - optional)
// ├── ParseLogMetrics()
// ├── GetLogParserScriptId()
// └── GetLogFileForParsing()
//
// SecurityProvider (security features - optional)
// ├── GetDefaultDetectionModel()
// └── GetRequiredSecretNames()
//
// CodingAgentEngine (composite - backward compatibility)
// └── Composes all above interfaces
//
// Usage Patterns:
//
// 1. For code that only needs identity information:
// func processEngine(e Engine) { ... }
//
// 2. For code that needs capability checks:
// func checkCapabilities(cp CapabilityProvider) { ... }
//
// 3. For backward compatibility (existing code):
// func compile(engine CodingAgentEngine) { ... }
//
// Implementation:
//
// All engines embed BaseEngine which provides default implementations for all methods.
// Engines can override specific methods to provide custom behavior.
//
// Example:
// type MyEngine struct {
// BaseEngine
// }
//
// func (e *MyEngine) GetInstallationSteps(...) []GitHubActionStep {
// // Custom implementation
// }

// Engine represents the core identity of an AI coding agent
// All engines must implement this interface to provide basic identification
type Engine interface {
// GetID returns the unique identifier for this engine
GetID() string

Expand All @@ -28,7 +102,11 @@ type CodingAgentEngine interface {

// IsExperimental returns true if this engine is experimental
IsExperimental() bool
}

// CapabilityProvider detects what capabilities an engine supports
// Engines can optionally implement this to indicate feature support
type CapabilityProvider interface {
// SupportsToolsAllowlist returns true if this engine supports MCP tool allow-listing
SupportsToolsAllowlist() bool

Expand All @@ -47,7 +125,11 @@ type CodingAgentEngine interface {
// SupportsFirewall returns true if this engine supports network firewalling/sandboxing
// When true, the engine can enforce network restrictions defined in the workflow
SupportsFirewall() bool
}

// WorkflowExecutor handles workflow compilation and execution
// All engines must implement this to generate GitHub Actions steps
type WorkflowExecutor interface {
// GetDeclaredOutputFiles returns a list of output files that this engine may produce
// These files will be automatically uploaded as artifacts if they exist
GetDeclaredOutputFiles() []string
Expand All @@ -57,10 +139,18 @@ type CodingAgentEngine interface {

// GetExecutionSteps returns the GitHub Actions steps for executing this engine
GetExecutionSteps(workflowData *WorkflowData, logFile string) []GitHubActionStep
}

// MCPConfigProvider handles MCP (Model Context Protocol) configuration
// Engines that support MCP servers should implement this
type MCPConfigProvider interface {
// RenderMCPConfig renders the MCP configuration for this engine to the given YAML builder
RenderMCPConfig(yaml *strings.Builder, tools map[string]any, mcpTools []string, workflowData *WorkflowData)
}

// LogParser handles parsing and analyzing engine logs
// Engines can optionally implement this to provide detailed log parsing
type LogParser interface {
// ParseLogMetrics extracts metrics from engine-specific log content
ParseLogMetrics(logContent string, verbose bool) LogMetrics

Expand All @@ -70,7 +160,11 @@ type CodingAgentEngine interface {
// GetLogFileForParsing returns the log file path to use for JavaScript parsing in the workflow
// This may be different from the stdout/stderr log file if the engine produces separate detailed logs
GetLogFileForParsing() string
}

// SecurityProvider handles security-related configuration
// Engines can optionally implement this to provide security features
type SecurityProvider interface {
// GetDefaultDetectionModel returns the default model to use for threat detection
// If empty, no default model is applied and the engine uses its standard default
GetDefaultDetectionModel() string
Expand All @@ -81,6 +175,18 @@ type CodingAgentEngine interface {
GetRequiredSecretNames(workflowData *WorkflowData) []string
}

// CodingAgentEngine is a composite interface that combines all focused interfaces
// This maintains backward compatibility with existing code while allowing more flexibility
// Implementations can choose to implement only the interfaces they need by embedding BaseEngine
type CodingAgentEngine interface {
Engine
CapabilityProvider
WorkflowExecutor
MCPConfigProvider
LogParser
SecurityProvider
}

// BaseEngine provides common functionality for agentic engines
type BaseEngine struct {
id string
Expand Down
Loading
Loading