Refactor engine.max-runs to top-level max-runs with AWF enforcement (#31418)

Author: Copilot

.github/aw/syntax.md

@@ -168,6 +168,9 @@ The YAML frontmatter supports these fields:
   - Bot must be active (installed) on repository to trigger workflow
 - **`strict:`** - Enable enhanced validation for production workflows (boolean, defaults to `true`)
   - Must be `true`
+- **`max-runs:`** - Maximum number of LLM invocations allowed per workflow run (integer or numeric string, minimum: 1)
+  - Top-level field mapped to `apiProxy.maxRuns`
+  - Supported by all engines
 - **`user-rate-limit:`** - Rate limiting configuration to prevent users from triggering the workflow too frequently (object)
   - **`max-runs-per-window:`** - Maximum runs allowed per user per time window (required, integer 1-10)
   - **`window:`** - Time window in minutes (integer 1-180, default: 60)

docs/adr/31418-move-engine-max-runs-to-top-level-with-awf-enforcement.md

@@ -0,0 +1,105 @@
+---
+name: ADR 31418 — Move engine.max-runs to top-level max-runs with AWF enforcement
+description: Canonicalize run-cap configuration as top-level `max-runs` and route enforcement through AWF (`apiProxy.maxRuns`) for all engines.
+type: project
+---
+
+# ADR-31418: Move `engine.max-runs` to Top-Level `max-runs` with AWF Enforcement
+
+**Date**: 2026-05-11
+**Status**: Draft
+**Deciders**: Unknown
+
+---
+
+## Part 1 — Narrative (Human-Friendly)
+
+### Context
+
+Run-cap configuration was previously expressed as the nested frontmatter field `engine.max-runs`, and enforcement was handled inconsistently across engines (Copilot/Claude/Codex/Gemini/Crush/OpenCode). The new AWF (Agent Workflow Framework) API proxy already centralizes other invocation-time policies (for example, `apiProxy.maxEffectiveTokens` and `apiProxy.modelMultipliers`), so it is the natural enforcement point for invocation caps as well. Without a single canonical place to declare the cap and a single enforcement point, behavior drifts per engine and the field is effectively unsupported on engines that have not implemented it. The repository already ships a codemod framework that can rewrite deprecated frontmatter automatically, which makes a deprecation path low-friction for existing workflows.
+
+### Decision
+
+We will canonicalize the run-cap configuration as a **top-level** frontmatter field `max-runs` and **route enforcement through AWF** by emitting it as `apiProxy.maxRuns` in the AWF config. The value is parsed once at the top level (accepting either an integer or a numeric string), stored on `EngineConfig.MaxRuns`, and forwarded to AWF; `engine.max-runs` is deprecated and migrated automatically via a new codemod (`engine-max-runs-to-top-level`). The field is omitted from `apiProxy` when unset so that no implicit cap is written.
+
+### Alternatives Considered
+
+#### Alternative 1: Keep `engine.max-runs` and implement per-engine enforcement
+
+Continue to expose the cap as a nested `engine.max-runs` field and have each engine wrapper enforce it. Rejected because this is the status quo that motivated the change: enforcement diverges between engines, several engines do not implement the cap at all, and there is no single place to reason about invocation limits.
+
+#### Alternative 2: Dual-support both `engine.max-runs` and top-level `max-runs`
+
+Accept both forms indefinitely and have the compiler merge them. Rejected because long-term dual support adds documentation surface, parsing precedence rules, and ongoing user confusion. The existing codemod infrastructure (see `pkg/cli/fix_codemods.go`) lets us migrate in place automatically, so the cost of deprecation is small.
+
+#### Alternative 3: Introduce a new name (e.g., `awf.maxRuns` or `invocation-cap`) at the top level
+
+Pick a different top-level name to signal the AWF-routed semantics. Rejected because users already think of the value as `max-runs`; renaming would force a larger documentation churn and a more disruptive codemod without changing behavior. The internal AWF field is already named `maxRuns`, so the mapping is transparent.
+
+### Consequences
+
+#### Positive
+- Run-cap enforcement is uniform across all engines because it is applied by the AWF API proxy, eliminating per-engine drift.
+- Workflow authors have a single, discoverable top-level field (`max-runs`) instead of a nested engine option.
+- Existing workflows are migrated automatically by the `engine-max-runs-to-top-level` codemod, so the deprecation is low-friction.
+- The schema, autocomplete metadata, and engine-feature table now advertise the cap as supported by every engine, which matches the new reality.
+
+#### Negative
+- `engine.max-runs` is now deprecated; users on older workflow files who do not run `fix` will see the nested field silently removed by the codemod next time it runs, which is a behavior change.
+- A new top-level frontmatter key expands the public configuration surface and must be kept in sync across schema, autocomplete, docs, parser, AWF config emitter, and codemods (six artifacts updated in this PR).
+- Enforcement now depends on AWF being in the request path; engines that bypass AWF would silently ignore `max-runs`. The PR assumes AWF is always present for runs that need the cap.
+
+#### Neutral
+- The omission semantics are preserved: when `max-runs` is unset, no `apiProxy.maxRuns` key is emitted (verified by `TestBuildAWFConfigJSON/max-runs omitted when not configured`).
+- The codemod preserves an already-present top-level value when both nested and top-level forms exist, choosing the top-level value (verified by `TestEngineMaxRunsToTopLevelCodemod_RespectsExistingTopLevel`).
+- Both integer and numeric-string inputs are accepted, matching the existing convention used for `max-effective-tokens`.
+
+---
+
+## Part 2 — Normative Specification (RFC 2119)
+
+> The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**, **SHOULD**, **SHOULD NOT**, **RECOMMENDED**, **MAY**, and **OPTIONAL** in this section are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).
+
+### Frontmatter Contract
+
+1. The canonical run-cap field **MUST** be the top-level frontmatter key `max-runs`.
+2. The value of `max-runs` **MUST** be either a positive integer or a numeric string that parses to a positive integer (minimum `1`).
+3. The compiler **MUST** reject or ignore values of `max-runs` that are not positive integers; non-positive or non-numeric values **MUST NOT** be propagated to `EngineConfig.MaxRuns`.
+4. The compiler **MUST NOT** require `max-runs` to be set; it is **OPTIONAL** frontmatter.
+
+### Engine Configuration Wiring
+
+1. `EngineConfig` **MUST** carry the parsed run-cap value on the `MaxRuns` field.
+2. `EngineConfig.MaxRuns` **MUST** be sourced from the top-level frontmatter `max-runs`, not from any nested `engine.max-runs` field.
+3. `EngineConfig.GetMaxRuns()` **MUST** return `0` when `MaxRuns` is unset or non-positive.
+4. The compiler **SHOULD** populate `MaxRuns` for every engine extraction path (string form, inline form, and named-engine form) so that the field is available regardless of how the engine is declared.
+
+### AWF API Proxy Emission
+
+1. When `EngineConfig.GetMaxRuns()` returns a positive integer, `BuildAWFConfigJSON` **MUST** emit `apiProxy.maxRuns` with that value.
+2. When `EngineConfig.GetMaxRuns()` returns `0`, `BuildAWFConfigJSON` **MUST NOT** emit the `maxRuns` key in the `apiProxy` section.
+3. The emitted JSON key **MUST** be exactly `maxRuns` (camelCase), matching the existing `apiProxy` field naming convention.
+
+### Deprecation and Migration
+
+1. The nested field `engine.max-runs` **MUST** be treated as deprecated.
+2. The codemod `engine-max-runs-to-top-level` **MUST** be registered in `GetAllCodemods()` and **MUST** run after `engine-steps-to-top-level` and before `steps-run-secrets-to-env` to preserve the established codemod ordering.
+3. When applied, the codemod **MUST** remove `engine.max-runs` from the nested `engine` block.
+4. When a top-level `max-runs` is absent, the codemod **MUST** insert a top-level `max-runs` line carrying the migrated value.
+5. When a top-level `max-runs` already exists, the codemod **MUST** preserve the existing top-level value and **MUST NOT** overwrite it with the nested value.
+6. The codemod **MUST** be a no-op when neither `engine.max-runs` nor a top-level `max-runs` is present.
+
+### Documentation and Tooling
+
+1. The workflow JSON schema (`pkg/parser/schemas/main_workflow_schema.json`) **MUST** declare `max-runs` as a top-level property with `oneOf` integer-or-numeric-string typing and a minimum of `1`.
+2. The autocomplete metadata (`docs/public/editor/autocomplete-data.json`) **MUST** advertise `max-runs` as a top-level leaf field.
+3. The engine feature table in `docs/src/content/docs/reference/engines.md` **MUST** mark `max-runs` as supported (`✅`) for every engine listed.
+4. New or updated documentation **SHOULD** describe `max-runs` as mapping to `awf.maxRuns` / `apiProxy.maxRuns`.
+
+### Conformance
+
+An implementation is considered conformant with this ADR if it satisfies all **MUST** and **MUST NOT** requirements above. Failure to meet any **MUST** or **MUST NOT** requirement constitutes non-conformance. In particular: emitting `apiProxy.maxRuns` when `max-runs` is unset, sourcing `MaxRuns` from `engine.max-runs` at runtime, or skipping codemod migration when both forms are present all constitute non-conformance.
+
+---
+
+*This is a DRAFT ADR generated by the [Design Decision Gate](https://github.com/github/gh-aw/actions/runs/25650796734) workflow. The PR author must review, complete, and finalize this document before the PR can merge.*

docs/public/editor/autocomplete-data.json

@@ -1176,6 +1176,11 @@
       "desc": "Explicit ET budget control for firewall cost enforcement.",
       "leaf": true
     },
+    "max-runs": {
+      "type": "integer|string",
+      "desc": "AWF invocation cap (`apiProxy.maxRuns`) applied consistently across all engines.",
+      "leaf": true
+    },
     "mcp-servers": {
       "type": "object",
       "desc": "MCP server definitions"
@@ -3435,4 +3440,4 @@
     "runtimes",
     "jobs"
   ]
-}
+}

docs/src/content/docs/reference/engines.md

@@ -32,6 +32,7 @@ Not all features are available across all engines. The table below summarizes pe
 
 | Feature | Copilot | Claude | Codex | Gemini | Crush | OpenCode |
 |---------|:-------:|:------:|:-----:|:------:|:-----:|:--------:|
+| `max-runs` (AWF invocation cap) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | `max-turns` | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
 | `max-continuations` | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
 | `tools.web-fetch` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
@@ -43,6 +44,7 @@ Not all features are available across all engines. The table below summarizes pe
 | Tools allowlist | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
 
 **Notes:**
+- `max-runs` is a top-level frontmatter field that maps to `apiProxy.maxRuns` and is supported by all engines.
 - `max-turns` limits the number of AI chat iterations per run (Claude only).
 - `max-continuations` enables autopilot mode with multiple consecutive runs (Copilot only).
 - `web-search` for Codex is disabled by default; add `tools: web-search:` to enable it. Other engines use a third-party MCP server — see [Using Web Search](/gh-aw/guides/web-search/).

pkg/cli/codemod_engine_max_runs.go

@@ -0,0 +1,98 @@
+package cli
+
+import (
+	"strings"
+
+	"github.com/github/gh-aw/pkg/logger"
+)
+
+var engineMaxRunsCodemodLog = logger.New("cli:codemod_engine_max_runs")
+
+// getEngineMaxRunsToTopLevelCodemod migrates deprecated engine.max-runs to
+// top-level max-runs.
+func getEngineMaxRunsToTopLevelCodemod() Codemod {
+	return Codemod{
+		ID:           "engine-max-runs-to-top-level",
+		Name:         "Move engine.max-runs to top-level max-runs",
+		Description:  "Moves deprecated 'engine.max-runs' to top-level 'max-runs' so AWF enforces invocation caps consistently across all engines.",
+		IntroducedIn: "0.17.0",
+		Apply: func(content string, frontmatter map[string]any) (string, bool, error) {
+			engineValue, hasEngine := frontmatter["engine"]
+			if !hasEngine {
+				return content, false, nil
+			}
+			engineMap, ok := engineValue.(map[string]any)
+			if !ok {
+				return content, false, nil
+			}
+			if _, hasMaxRuns := engineMap["max-runs"]; !hasMaxRuns {
+				return content, false, nil
+			}
+
+			_, hasTopLevelMaxRuns := frontmatter["max-runs"]
+
+			return applyFrontmatterLineTransform(content, func(lines []string) ([]string, bool) {
+				for _, line := range lines {
+					trimmed := strings.TrimSpace(line)
+					if !isTopLevelKey(line) || !strings.HasPrefix(trimmed, "engine:") {
+						continue
+					}
+					inlineValue := strings.TrimSpace(strings.TrimPrefix(trimmed, "engine:"))
+					if strings.HasPrefix(inlineValue, "{") && strings.Contains(inlineValue, "max-runs:") {
+						engineMaxRunsCodemodLog.Print("Skipping engine.max-runs migration for inline-map engine syntax; migrate to top-level max-runs manually")
+						return lines, false
+					}
+				}
+
+				maxRunsSuffix := ""
+				inEngineBlock := false
+				engineIndent := ""
+				for _, line := range lines {
+					trimmed := strings.TrimSpace(line)
+					if isTopLevelKey(line) && strings.HasPrefix(trimmed, "engine:") {
+						inEngineBlock = true
+						engineIndent = getIndentation(line)
+						continue
+					}
+					if inEngineBlock && len(trimmed) > 0 && !strings.HasPrefix(trimmed, "#") && len(getIndentation(line)) <= len(engineIndent) {
+						inEngineBlock = false
+					}
+					if inEngineBlock && strings.HasPrefix(trimmed, "max-runs:") {
+						parts := strings.SplitN(line, ":", 2)
+						if len(parts) == 2 {
+							maxRunsSuffix = parts[1]
+						}
+						break
+					}
+				}
+
+				result, removed := removeFieldFromBlock(lines, "max-runs", "engine")
+				if !removed {
+					return lines, false
+				}
+
+				if hasTopLevelMaxRuns {
+					engineMaxRunsCodemodLog.Print("Removed deprecated engine.max-runs (top-level max-runs already present)")
+					return result, true
+				}
+
+				insertAt := 0
+				for i, line := range result {
+					if isTopLevelKey(line) && strings.HasPrefix(strings.TrimSpace(line), "engine:") {
+						insertAt = i
+						break
+					}
+				}
+
+				maxRunsLine := "max-runs:" + maxRunsSuffix
+				withTopLevel := make([]string, 0, len(result)+1)
+				withTopLevel = append(withTopLevel, result[:insertAt]...)
+				withTopLevel = append(withTopLevel, maxRunsLine)
+				withTopLevel = append(withTopLevel, result[insertAt:]...)
+
+				engineMaxRunsCodemodLog.Print("Migrated engine.max-runs to top-level max-runs")
+				return withTopLevel, true
+			})
+		},
+	}
+}

pkg/cli/codemod_engine_max_runs_test.go

@@ -0,0 +1,116 @@
+//go:build !integration
+
+package cli
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestEngineMaxRunsToTopLevelCodemod_Metadata(t *testing.T) {
+	codemod := getEngineMaxRunsToTopLevelCodemod()
+
+	assert.Equal(t, "engine-max-runs-to-top-level", codemod.ID)
+	assert.Equal(t, "Move engine.max-runs to top-level max-runs", codemod.Name)
+	assert.NotEmpty(t, codemod.Description)
+	assert.Equal(t, "0.17.0", codemod.IntroducedIn)
+	require.NotNil(t, codemod.Apply)
+}
+
+func TestEngineMaxRunsToTopLevelCodemod_NoOp(t *testing.T) {
+	codemod := getEngineMaxRunsToTopLevelCodemod()
+
+	content := `---
+on: push
+engine:
+  id: copilot
+---
+`
+	frontmatter := map[string]any{
+		"on": "push",
+		"engine": map[string]any{
+			"id": "copilot",
+		},
+	}
+
+	result, applied, err := codemod.Apply(content, frontmatter)
+	require.NoError(t, err)
+	assert.False(t, applied)
+	assert.Equal(t, content, result)
+}
+
+func TestEngineMaxRunsToTopLevelCodemod_MigratesField(t *testing.T) {
+	codemod := getEngineMaxRunsToTopLevelCodemod()
+
+	content := `---
+on: push
+engine:
+  id: copilot
+  max-runs: 42
+---
+
+# Body`
+	frontmatter := map[string]any{
+		"on": "push",
+		"engine": map[string]any{
+			"id":       "copilot",
+			"max-runs": 42,
+		},
+	}
+
+	result, applied, err := codemod.Apply(content, frontmatter)
+	require.NoError(t, err)
+	assert.True(t, applied)
+	assert.Contains(t, result, "\nmax-runs: 42\nengine:")
+	assert.NotContains(t, result, "\n  max-runs:")
+}
+
+func TestEngineMaxRunsToTopLevelCodemod_RespectsExistingTopLevel(t *testing.T) {
+	codemod := getEngineMaxRunsToTopLevelCodemod()
+
+	content := `---
+max-runs: 10
+engine:
+  id: copilot
+  max-runs: 42
+---
+`
+	frontmatter := map[string]any{
+		"max-runs": 10,
+		"engine": map[string]any{
+			"id":       "copilot",
+			"max-runs": 42,
+		},
+	}
+
+	result, applied, err := codemod.Apply(content, frontmatter)
+	require.NoError(t, err)
+	assert.True(t, applied)
+	assert.Contains(t, result, "max-runs: 10")
+	assert.NotContains(t, result, "max-runs: 42")
+	assert.NotContains(t, result, "\n  max-runs:")
+}
+
+func TestEngineMaxRunsToTopLevelCodemod_InlineEngineMapNoOp(t *testing.T) {
+	codemod := getEngineMaxRunsToTopLevelCodemod()
+
+	content := `---
+on: push
+engine: { id: copilot, max-runs: 42 }
+---
+`
+	frontmatter := map[string]any{
+		"on": "push",
+		"engine": map[string]any{
+			"id":       "copilot",
+			"max-runs": 42,
+		},
+	}
+
+	result, applied, err := codemod.Apply(content, frontmatter)
+	require.NoError(t, err)
+	assert.False(t, applied)
+	assert.Equal(t, content, result)
+}

pkg/cli/fix_codemods.go

@@ -43,6 +43,7 @@ func GetAllCodemods() []Codemod {
 		getRolesToOnRolesCodemod(),                    // Move top-level roles to on.roles
 		getBotsToOnBotsCodemod(),                      // Move top-level bots to on.bots
 		getEngineStepsToTopLevelCodemod(),             // Move engine.steps to top-level steps
+		getEngineMaxRunsToTopLevelCodemod(),           // Move engine.max-runs to top-level max-runs
 		getStepsRunSecretsToEnvCodemod(),              // Move inline secrets in step run fields to step env bindings
 		getEngineEnvSecretsCodemod(),                  // Remove unsafe secret-bearing engine.env entries
 		getAssignToAgentDefaultAgentCodemod(),         // Rename deprecated default-agent to name in assign-to-agent

pkg/cli/fix_codemods_test.go

@@ -82,6 +82,7 @@ func TestGetAllCodemods_ContainsExpectedCodemods(t *testing.T) {
 		"mcp-network-to-top-level-migration",
 		"safe-inputs-to-mcp-scripts",
 		"rate-limit-to-user-rate-limit",
+		"engine-max-runs-to-top-level",
 		"steps-run-secrets-to-env",
 		"engine-env-secrets-to-engine-config",
 		"serena-tools-to-shared-import",
@@ -145,6 +146,7 @@ func expectedCodemodOrder() []string {
 		"roles-to-on-roles",
 		"bots-to-on-bots",
 		"engine-steps-to-top-level",
+		"engine-max-runs-to-top-level",
 		"steps-run-secrets-to-env",
 		"engine-env-secrets-to-engine-config",
 		"assign-to-agent-default-agent-to-name",