feat(workflow): support sandbox.agent.version and migrate deprecated network.firewall to sandbox.agent

docs/adr/27626-sandbox-agent-version-and-network-firewall-migration.md

@@ -0,0 +1,76 @@
+# ADR-27626: Introduce sandbox.agent.version and Remove Deprecated network.firewall Field
+
+**Date**: 2026-04-21
+**Status**: Draft
+**Deciders**: Unknown (copilot-swe-agent / pelikhan)
+
+---
+
+## Part 1 — Narrative (Human-Friendly)
+
+### Context
+
+The `network.firewall` frontmatter field was previously used to configure the Agent Workflow Firewall (AWF) in agentic workflow definitions. It was deprecated in favor of the unified `sandbox.agent` configuration block, but the migration codemod only handled the `true` case, leaving `false`, `null`, `"disable"`, and object-with-version forms unmigrated. Additionally, there was no mechanism to pin a specific AWF version via frontmatter — users who needed to run a particular AWF release had no stable, documented way to express that constraint. This PR addresses both gaps simultaneously: removing the deprecated field from the schema and expanding the codemod to cover all value variants.
+
+### Decision
+
+We will remove `network.firewall` from the frontmatter schema entirely and add `sandbox.agent.version` as a first-class string field for pinning the AWF version used during installation and runtime. The codemod will be expanded to migrate all `network.firewall` value forms — `true`, `false`, `null`, `"disable"`, and `{version: ...}` objects — to their `sandbox.agent` equivalents. This consolidates AWF configuration under a single `sandbox.agent` surface and ensures the migration path covers every variant that appears in the wild.
+
+### Alternatives Considered
+
+#### Alternative 1: Retain network.firewall as a Deprecated Alias
+
+Keep `network.firewall` in the schema with a deprecation warning, parsing it alongside `sandbox.agent` and merging the values at runtime. This avoids a hard removal and gives teams more migration runway, but perpetuates two competing configuration surfaces indefinitely, increases parser complexity, and makes it harder to reason about precedence when both fields are set.
+
+#### Alternative 2: Introduce a Flat sandbox.awf-version Field
+
+Add a top-level sibling key `sandbox.awf-version` (or similar) rather than nesting the version under `sandbox.agent`. This is marginally more ergonomic to type but diverges from the `sandbox.agent` object model already established, creates a second place where AWF version information lives, and complicates the precedence rules for effective version resolution.
+
+### Consequences
+
+#### Positive
+- All `network.firewall` value forms now have a deterministic, tested migration path to `sandbox.agent`.
+- Users can pin an explicit AWF version via `sandbox.agent.version`, enabling reproducible builds without relying on the latest release.
+- The schema surface is reduced by removing a deprecated field and its associated validation rules.
+
+#### Negative
+- Behavioral change: `network.firewall: false` previously produced no `sandbox` block; it now migrates to `sandbox.agent: false`. Workflows relying on the old no-op behavior will see a new block added by the codemod.
+- The `normalizeFirewallVersion` helper must handle all numeric YAML types (int8 through uint64, float32/float64) because YAML parsers may unmarshal numeric version values into any of these types, increasing codemod surface area.
+
+#### Neutral
+- The codemod expansion requires updating existing tests that asserted `sandbox:` was *not* added for `false` and nested object cases; these expectations were inverted.
+- The `aw-info` AWF version reporting now reads `sandbox.agent.version` in addition to the legacy `firewallVersion` field, requiring both paths to be tested.
+
+---
+
+## 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 Schema
+
+1. Implementations **MUST NOT** include `network.firewall` in the frontmatter schema as a valid, non-deprecated field.
+2. Implementations **MUST** expose `sandbox.agent.version` as an optional string field in the frontmatter schema for specifying an AWF version override.
+3. The `sandbox.agent.version` field **MUST** be treated as a string type; numeric-like values written in YAML **MUST** be quoted at generation time to prevent YAML parsers from interpreting them as numbers.
+
+### Codemod Migration
+
+1. The `network.firewall` codemod **MUST** produce a `sandbox.agent` block for every non-absent value of `network.firewall`, including `true`, `false`, `null`, `"disable"`, and object forms.
+2. When `network.firewall` is `true` or `null`, the codemod **MUST** emit `sandbox.agent: awf`.
+3. When `network.firewall` is `false` or `"disable"`, the codemod **MUST** emit `sandbox.agent: false`.
+4. When `network.firewall` is an object containing a `version` key, the codemod **MUST** emit a `sandbox.agent` object block with `id: awf` and `version: "<migrated-value>"`.
+5. The codemod **MUST NOT** add a `sandbox` block when one already exists in the frontmatter.
+6. Numeric version values encountered during migration **MUST** be normalized to their string representation before being written as `sandbox.agent.version`.
+
+### AWF Version Resolution
+
+1. When `sandbox.agent.version` is set, it **MUST** take precedence over any version derived from the legacy `network.firewall` configuration when resolving the effective AWF version for installation and runtime.
+2. Implementations **SHOULD** surface the resolved AWF version in `aw-info` metadata so that workflow authors can verify which version is active.
+
+### 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.
+
+---
+
+*This is a DRAFT ADR generated by the [Design Decision Gate](https://github.com/github/gh-aw/actions/runs/24736713102) workflow. The PR author must review, complete, and finalize this document before the PR can merge.*

docs/src/content/docs/reference/frontmatter-full.md

@@ -1309,6 +1309,10 @@ sandbox:
     # (optional)
     type: "awf"
 
+    # AWF version override used to install and run the matching firewall version.
+    # (optional)
+    version: "example-value"
+
     # Container mounts to add when using AWF. Each mount is specified using Docker
     # mount syntax: 'source:destination:mode' where mode can be 'ro' (read-only) or
     # 'rw' (read-write). Example: '/host/path:/container/path:ro'

pkg/cli/codemod_network_firewall.go

@@ -1,6 +1,7 @@
 package cli
 
 import (
+	"strconv"
 	"strings"
 
 	"github.com/github/gh-aw/pkg/logger"
@@ -20,53 +21,242 @@ func getNetworkFirewallCodemod() Codemod {
 		LogMsg:       "Applied network.firewall migration (firewall now always enabled via sandbox.agent: awf default)",
 		Log:          networkFirewallCodemodLog,
 		PostTransform: func(lines []string, frontmatter map[string]any, fieldValue any) []string {
-			// Note: We no longer set sandbox.agent: false since the firewall is mandatory
-			// The firewall is always enabled via the default sandbox.agent: awf
-
 			_, hasSandbox := frontmatter["sandbox"]
 
-			// Add sandbox.agent if not already present AND if firewall was explicitly true
-			// (no need to add sandbox.agent: awf if firewall was false, since awf is now the default)
-			if !hasSandbox && fieldValue == true {
-				// Only add sandbox.agent: awf if firewall was explicitly set to true
-				sandboxLines := []string{
-					"sandbox:",
-					"  agent: awf  # Firewall enabled (migrated from network.firewall)",
+			if !hasSandbox {
+				sandboxLines := sandboxAgentLinesFromFirewall(fieldValue)
+				if len(sandboxLines) > 0 {
+					lines = insertSandboxAfterNetworkBlock(lines, sandboxLines)
+					networkFirewallCodemodLog.Print("Converted deprecated network.firewall to sandbox.agent")
 				}
+				return lines
+			}
 
-				// Try to place it after network block
-				insertIndex := -1
-				inNet := false
-				for i, line := range lines {
-					trimmed := strings.TrimSpace(line)
-					if strings.HasPrefix(trimmed, "network:") {
-						inNet = true
-					} else if inNet && len(trimmed) > 0 {
-						// Check if this is a top-level key (no leading whitespace)
-						if isTopLevelKey(line) {
-							// Found next top-level key
-							insertIndex = i
-							break
-						}
-					}
-				}
+			lines, merged := mergeFirewallIntoExistingSandbox(lines, fieldValue)
+			if merged {
+				networkFirewallCodemodLog.Print("Merged deprecated network.firewall into existing sandbox.agent")
+			}
+			return lines
+		},
+	})
+}
 
-				if insertIndex >= 0 {
-					// Insert after network block
-					newLines := make([]string, 0, len(lines)+len(sandboxLines))
-					newLines = append(newLines, lines[:insertIndex]...)
-					newLines = append(newLines, sandboxLines...)
-					newLines = append(newLines, lines[insertIndex:]...)
-					lines = newLines
-				} else {
-					// Append at the end
-					lines = append(lines, sandboxLines...)
+func sandboxAgentLinesFromFirewall(fieldValue any) []string {
+	switch value := fieldValue.(type) {
+	case bool:
+		if value {
+			return []string{
+				"sandbox:",
+				"  agent: awf  # Migrated from deprecated network setting",
+			}
+		}
+		return []string{
+			"sandbox:",
+			"  agent: false  # Migrated from deprecated network setting",
+		}
+	case string:
+		if strings.EqualFold(strings.TrimSpace(value), "disable") {
+			return []string{
+				"sandbox:",
+				"  agent: false  # Migrated from deprecated network setting",
+			}
+		}
+	case map[string]any:
+		versionValue, hasVersion := value["version"]
+		if hasVersion {
+			if version, ok := normalizeFirewallVersion(versionValue); ok {
+				return []string{
+					"sandbox:",
+					"  agent:",
+					"    id: awf  # Migrated from deprecated network setting",
+					"    version: " + formatSandboxVersionYAML(version),
 				}
+			}
+		}
+		return []string{
+			"sandbox:",
+			"  agent: awf  # Migrated from deprecated network setting",
+		}
+	case nil:
+		return []string{
+			"sandbox:",
+			"  agent: awf  # Migrated from deprecated network setting",
+		}
+	}
+	return nil
+}
+
+func normalizeFirewallVersion(versionValue any) (string, bool) {
+	switch value := versionValue.(type) {
+	case string:
+		trimmed := strings.TrimSpace(value)
+		return trimmed, trimmed != ""
+	case int:
+		return strconv.Itoa(value), true
+	case int8:
+		return strconv.FormatInt(int64(value), 10), true
+	case int16:
+		return strconv.FormatInt(int64(value), 10), true
+	case int32:
+		return strconv.FormatInt(int64(value), 10), true
+	case int64:
+		return strconv.FormatInt(value, 10), true
+	case uint:
+		return strconv.FormatUint(uint64(value), 10), true
+	case uint8:
+		return strconv.FormatUint(uint64(value), 10), true
+	case uint16:
+		return strconv.FormatUint(uint64(value), 10), true
+	case uint32:
+		return strconv.FormatUint(uint64(value), 10), true
+	case uint64:
+		return strconv.FormatUint(value, 10), true
+	case float32:
+		return strconv.FormatFloat(float64(value), 'f', -1, 32), true
+	case float64:
+		return strconv.FormatFloat(value, 'f', -1, 64), true
+	default:
+		return "", false
+	}
+}
+
+func formatSandboxVersionYAML(version string) string {
+	// Always quote because sandbox.agent.version is a string field, and this prevents
+	// YAML from interpreting numeric-like versions as numbers.
+	return strconv.Quote(version)
+}
+
+func insertSandboxAfterNetworkBlock(lines []string, sandboxLines []string) []string {
+	insertIndex := -1
+	inNetworkBlock := false
+	for i, line := range lines {
+		trimmed := strings.TrimSpace(line)
+		if strings.HasPrefix(trimmed, "network:") {
+			inNetworkBlock = true
+			continue
+		}
+		if inNetworkBlock && len(trimmed) > 0 && isTopLevelKey(line) {
+			insertIndex = i
+			break
+		}
+	}
 
-				networkFirewallCodemodLog.Print("Added sandbox.agent: awf (firewall was explicitly enabled)")
+	if insertIndex >= 0 {
+		newLines := make([]string, 0, len(lines)+len(sandboxLines))
+		newLines = append(newLines, lines[:insertIndex]...)
+		newLines = append(newLines, sandboxLines...)
+		newLines = append(newLines, lines[insertIndex:]...)
+		return newLines
+	}
+
+	return append(lines, sandboxLines...)
+}
+
+func mergeFirewallIntoExistingSandbox(lines []string, fieldValue any) ([]string, bool) {
+	agentLines := sandboxAgentLinesForExistingSandbox(fieldValue)
+	if len(agentLines) == 0 {
+		return lines, false
+	}
+
+	sandboxIdx := -1
+	for i, line := range lines {
+		trimmed := strings.TrimSpace(line)
+		if isTopLevelKey(line) && strings.HasPrefix(trimmed, "sandbox:") {
+			sandboxIdx = i
+			break
+		}
+	}
+	if sandboxIdx == -1 {
+		return lines, false
+	}
+
+	sandboxIndent := getIndentation(lines[sandboxIdx])
+	agentIndent := sandboxIndent + "  "
+	sandboxEnd := len(lines)
+	for i := sandboxIdx + 1; i < len(lines); i++ {
+		if isTopLevelKey(lines[i]) {
+			sandboxEnd = i
+			break
+		}
+	}
+
+	agentStart := -1
+	for i := sandboxIdx + 1; i < sandboxEnd; i++ {
+		trimmed := strings.TrimSpace(lines[i])
+		if strings.HasPrefix(trimmed, "agent:") && getIndentation(lines[i]) == agentIndent {
+			agentStart = i
+			break
+		}
+	}
+
+	indentedAgentLines := indentLines(agentLines, agentIndent)
+	if agentStart == -1 {
+		newLines := make([]string, 0, len(lines)+len(indentedAgentLines))
+		newLines = append(newLines, lines[:sandboxIdx+1]...)
+		newLines = append(newLines, indentedAgentLines...)
+		newLines = append(newLines, lines[sandboxIdx+1:]...)
+		return newLines, true
+	}
+
+	agentEnd := agentStart + 1
+	agentFieldIndent := getIndentation(lines[agentStart])
+	for agentEnd < sandboxEnd {
+		trimmed := strings.TrimSpace(lines[agentEnd])
+		if trimmed == "" {
+			agentEnd++
+			continue
+		}
+		if strings.HasPrefix(trimmed, "#") {
+			if len(getIndentation(lines[agentEnd])) > len(agentFieldIndent) {
+				agentEnd++
+				continue
 			}
+			break
+		}
+		if len(getIndentation(lines[agentEnd])) > len(agentFieldIndent) {
+			agentEnd++
+			continue
+		}
+		break
+	}
 
-			return lines
-		},
-	})
+	newLines := make([]string, 0, len(lines)-((agentEnd-agentStart)-len(indentedAgentLines)))
+	newLines = append(newLines, lines[:agentStart]...)
+	newLines = append(newLines, indentedAgentLines...)
+	newLines = append(newLines, lines[agentEnd:]...)
+	return newLines, true
+}
+
+func sandboxAgentLinesForExistingSandbox(fieldValue any) []string {
+	switch value := fieldValue.(type) {
+	case bool:
+		if !value {
+			return []string{"agent: false  # Migrated from deprecated network setting"}
+		}
+	case string:
+		if strings.EqualFold(strings.TrimSpace(value), "disable") {
+			return []string{"agent: false  # Migrated from deprecated network setting"}
+		}
+	case map[string]any:
+		versionValue, hasVersion := value["version"]
+		if hasVersion {
+			if version, ok := normalizeFirewallVersion(versionValue); ok {
+				return []string{
+					"agent:",
+					"  id: awf  # Migrated from deprecated network setting",
+					"  version: " + formatSandboxVersionYAML(version),
+				}
+			}
+		}
+	}
+
+	return nil
+}
+
+func indentLines(lines []string, indent string) []string {
+	indented := make([]string, 0, len(lines))
+	for _, line := range lines {
+		indented = append(indented, indent+line)
+	}
+	return indented
 }