Phase 3: Extend schema and parser for inline and catalog-defined engine definitions (#20469)

Author: Copilot

pkg/parser/schemas/main_workflow_schema.json

@@ -7778,22 +7778,41 @@
 "group": "gh-aw-claude",
 "cancel-in-progress": false
  }
+ },
+ {
+"runtime": {
+"id": "codex",
+"version": "0.105.0"
+ },
+"provider": {
+"id": "openai",
+"model": "gpt-5",
+"auth": {
+"secret": "OPENAI_API_KEY"
+ }
+ }
+ },
+ {
+"runtime": {
+"id": "claude"
+ },
+"provider": {
+"model": "claude-3-7-sonnet-20250219"
+ }
  }
  ],
 "oneOf": [
  {
 "type": "string",
-"enum": ["claude", "codex", "copilot", "gemini"],
-"description": "Simple engine name: 'claude' (default, Claude Code), 'copilot' (GitHub Copilot CLI), 'codex' (OpenAI Codex CLI), or 'gemini' (Google Gemini CLI)"
+"description": "Engine name: built-in ('claude', 'codex', 'copilot', 'gemini') or a named catalog entry"
  },
  {
 "type": "object",
 "description": "Extended engine configuration object with advanced options for model selection, turn limiting, environment variables, and custom steps",
 "properties": {
 "id": {
 "type": "string",
-"enum": ["claude", "codex", "copilot", "gemini"],
-"description": "AI engine identifier: 'claude' (Claude Code), 'codex' (OpenAI Codex CLI), 'copilot' (GitHub Copilot CLI), or 'gemini' (Google Gemini CLI)"
+"description": "AI engine identifier: built-in ('claude', 'codex', 'copilot', 'gemini') or a named catalog entry"
  },
 "version": {
 "type": ["string", "number"],
@@ -7914,6 +7933,61 @@
  },
 "required": ["id"],
 "additionalProperties": false
+ },
+ {
+"type": "object",
+"description": "Inline engine definition: specifies a runtime adapter and optional provider settings directly in the workflow frontmatter, without requiring a named catalog entry",
+"properties": {
+"runtime": {
+"type": "object",
+"description": "Runtime adapter reference for the inline engine definition",
+"properties": {
+"id": {
+"type": "string",
+"description": "Runtime adapter identifier (e.g. 'codex', 'claude', 'copilot', 'gemini')",
+"examples": ["codex", "claude", "copilot", "gemini"]
+ },
+"version": {
+"type": ["string", "number"],
+"description": "Optional version of the runtime adapter (e.g. '0.105.0', 'beta')",
+"examples": ["0.105.0", "beta", "latest"]
+ }
+ },
+"required": ["id"],
+"additionalProperties": false
+ },
+"provider": {
+"type": "object",
+"description": "Optional provider configuration for the inline engine definition",
+"properties": {
+"id": {
+"type": "string",
+"description": "Provider identifier (e.g. 'openai', 'anthropic', 'github', 'google')",
+"examples": ["openai", "anthropic", "github", "google"]
+ },
+"model": {
+"type": "string",
+"description": "Optional specific LLM model to use (e.g. 'gpt-5', 'claude-3-5-sonnet-20241022')",
+"examples": ["gpt-5", "claude-3-5-sonnet-20241022", "gpt-4o"]
+ },
+"auth": {
+"type": "object",
+"description": "Authentication configuration for the provider",
+"properties": {
+"secret": {
+"type": "string",
+"description": "Name of the GitHub Actions secret that contains the API key for this provider",
+"examples": ["OPENAI_API_KEY", "ANTHROPIC_API_KEY", "CUSTOM_API_KEY"]
+ }
+ },
+"additionalProperties": false
+ }
+ },
+"additionalProperties": false
+ }
+ },
+"required": ["runtime"],
+"additionalProperties": false
  }
  ]
  },

pkg/workflow/compiler_orchestrator_engine.go

@@ -36,6 +36,15 @@ func (c *Compiler) setupEngineAndImports(result *parser.FrontmatterResult, clean
 // Extract AI engine setting from frontmatter
 engineSetting, engineConfig:=c.ExtractEngineConfig(result.Frontmatter)
 
+// Validate and register inline engine definitions (engine.runtime sub-object).
+// Must happen before catalog resolution so the inline definition is visible to Resolve().
+ifengineConfig!=nil&&engineConfig.IsInlineDefinition {
+iferr:=c.validateEngineInlineDefinition(engineConfig); err!=nil {
+returnnil, err
+ }
+c.registerInlineEngineDefinition(engineConfig)
+	}
+
 // Extract network permissions from frontmatter
 networkPermissions:=c.extractNetworkPermissions(result.Frontmatter)
 

pkg/workflow/engine.go

@@ -26,6 +26,11 @@ type EngineConfig struct {
 Args []string
 Firewall*FirewallConfig// AWF firewall configuration
 Agentstring// Agent identifier for copilot --agent flag (copilot engine only)
+
+// Inline definition fields (populated when engine.runtime is specified in frontmatter)
+IsInlineDefinitionbool// true when the engine is defined inline via engine.runtime + optional engine.provider
+InlineProviderIDstring// engine.provider.id (e.g. "openai", "anthropic")
+InlineProviderSecretstring// engine.provider.auth.secret (name of the GitHub Actions secret for the provider API key)
 }
 
 // NetworkPermissions represents network access permissions for workflow execution
@@ -87,6 +92,44 @@ func (c *Compiler) ExtractEngineConfig(frontmatter map[string]any) (string, *Eng
 engineLog.Print("Found engine in object format, parsing configuration")
 config:=&EngineConfig{}
 
+// Detect inline definition: engine.runtime sub-object present instead of engine.id
+ifruntime, hasRuntime:=engineObj["runtime"]; hasRuntime {
+engineLog.Print("Found inline engine definition (engine.runtime sub-object)")
+config.IsInlineDefinition=true
+
+ifruntimeObj, ok:=runtime.(map[string]any); ok {
+ifid, ok:=runtimeObj["id"].(string); ok {
+config.ID=id
+engineLog.Printf("Inline engine runtime.id: %s", config.ID)
+ }
+ifversion, hasVersion:=runtimeObj["version"]; hasVersion {
+config.Version=stringutil.ParseVersionValue(version)
+ }
+ }
+
+// Extract optional provider sub-object
+ifprovider, hasProvider:=engineObj["provider"]; hasProvider {
+ifproviderObj, ok:=provider.(map[string]any); ok {
+ifid, ok:=providerObj["id"].(string); ok {
+config.InlineProviderID=id
+ }
+ifmodel, ok:=providerObj["model"].(string); ok {
+config.Model=model
+ }
+ifauth, hasAuth:=providerObj["auth"]; hasAuth {
+ifauthObj, ok:=auth.(map[string]any); ok {
+ifsecret, ok:=authObj["secret"].(string); ok {
+config.InlineProviderSecret=secret
+ }
+ }
+ }
+ }
+ }
+
+engineLog.Printf("Extracted inline engine definition: runtimeID=%s, providerID=%s", config.ID, config.InlineProviderID)
+returnconfig.ID, config
+ }
+
 // Extract required 'id' field
 ifid, hasID:=engineObj["id"]; hasID {
 ifidStr, ok:=id.(string); ok {

pkg/workflow/engine_catalog_test.go

@@ -61,9 +61,9 @@ func TestEngineCatalog_All(t *testing.T) {
 	}
 }
 
-// engineSchemaEnums parses the main workflow schema and extracts engine enum values
-// from both the string variant and the object id property of engine_config.
-funcengineSchemaEnums(t*testing.T) []string {
+// engineSchemaOneOfVariants parses the main workflow schema and returns the
+// type identifiers of each variant in engine_config.oneOf for structural assertions.
+funcengineSchemaOneOfVariants(t*testing.T) []map[string]any {
 t.Helper()
 
 schemaBytes, err:=os.ReadFile("../parser/schemas/main_workflow_schema.json")
@@ -81,40 +81,63 @@ func engineSchemaEnums(t *testing.T) []string {
 oneOf, ok:=engineConfig["oneOf"].([]any)
 require.True(t, ok, "engine_config should have oneOf")
 
-// The first oneOf variant is the plain string enum
-for_, variant:=rangeoneOf {
-v, ok:=variant.(map[string]any)
-if!ok {
-continue
- }
-ifv["type"] =="string" {
-rawEnum, ok:=v["enum"].([]any)
-if!ok {
-continue
- }
-enums:=make([]string, 0, len(rawEnum))
-for_, e:=rangerawEnum {
-ifs, ok:=e.(string); ok {
-enums=append(enums, s)
- }
- }
-sort.Strings(enums)
-returnenums
+variants:=make([]map[string]any, 0, len(oneOf))
+for_, v:=rangeoneOf {
+ifm, ok:=v.(map[string]any); ok {
+variants=append(variants, m)
  }
 	}
-t.Fatal("could not find string enum in engine_config oneOf")
-returnnil
+returnvariants
 }
 
-// TestEngineCatalogMatchesSchema asserts that the schema engine enum values exactly
-// match the catalog IDs. A failure here means the schema and catalog have drifted apart.
-funcTestEngineCatalogMatchesSchema(t*testing.T) {
+// TestEngineCatalog_BuiltInsPresent verifies that the four built-in engines are always
+// registered in the catalog with stable IDs.
+funcTestEngineCatalog_BuiltInsPresent(t*testing.T) {
 registry:=NewEngineRegistry()
 catalog:=NewEngineCatalog(registry)
 
-catalogIDs:=catalog.IDs() // already sorted
-schemaEnums:=engineSchemaEnums(t)
+expected:= []string{"claude", "codex", "copilot", "gemini"}
+catalogIDs:=catalog.IDs()
+for_, id:=rangeexpected {
+assert.Contains(t, catalogIDs, id,
+"built-in engine %q must always be present in the catalog", id)
+	}
+}
 
-assert.Equal(t, catalogIDs, schemaEnums,
-"schema engine enum must match catalog IDs exactly — run 'make build' after updating the schema")
+// TestEngineCatalogMatchesSchema asserts that the engine_config schema has the expected
+// structure: a plain-string variant (for built-ins and named catalog entries), an
+// object-with-id variant, and an inline-definition variant (object-with-runtime).
+// A failure here means the schema structure has changed unexpectedly.
+funcTestEngineCatalogMatchesSchema(t*testing.T) {
+variants:=engineSchemaOneOfVariants(t)
+
+require.Len(t, variants, 3, "engine_config oneOf should have exactly 3 variants: string, object-with-id, object-with-runtime")
+
+// Variant 0: plain string (no enum — allows built-ins and custom named catalog entries)
+assert.Equal(t, "string", variants[0]["type"],
+"first variant should be type string")
+assert.Nil(t, variants[0]["enum"],
+"string variant must NOT have an enum so that named catalog entries are allowed")
+
+// Variant 1: object with 'id' field for extended engine configuration
+assert.Equal(t, "object", variants[1]["type"],
+"second variant should be type object (extended config with id)")
+props1, ok:=variants[1]["properties"].(map[string]any)
+require.True(t, ok, "second variant should have properties")
+assert.Contains(t, props1, "id",
+"second variant should have an 'id' property")
+idProp, ok:=props1["id"].(map[string]any)
+require.True(t, ok, "id property should be a map")
+assert.Nil(t, idProp["enum"],
+"id property must NOT have an enum so that named catalog entries are allowed")
+
+// Variant 2: object with 'runtime' sub-object for inline definitions
+assert.Equal(t, "object", variants[2]["type"],
+"third variant should be type object (inline definition with runtime)")
+props2, ok:=variants[2]["properties"].(map[string]any)
+require.True(t, ok, "third variant should have properties")
+assert.Contains(t, props2, "runtime",
+"third variant should have a 'runtime' property for inline engine definitions")
+assert.Contains(t, props2, "provider",
+"third variant should have a 'provider' property for inline engine definitions")
 }

pkg/workflow/engine_definition.go

@@ -137,6 +137,11 @@ func (c *EngineCatalog) Register(def *EngineDefinition) {
 c.definitions[def.ID] =def
 }
 
+// Get returns the EngineDefinition for the given ID, or nil if not found.
+func (c*EngineCatalog) Get(idstring) *EngineDefinition {
+returnc.definitions[id]
+}
+
 // IDs returns a sorted list of all engine IDs in the catalog.
 func (c*EngineCatalog) IDs() []string {
 ids:=make([]string, 0, len(c.definitions))