Merge pull request #3550 from dgageot/feat/config-version-hint

feat(config): hint when a config key requires a newer schema version

Author: dgageot

pkg/config/config.go

@@ -11,6 +11,7 @@ import (
 	"os"
 	"path/filepath"
 	"slices"
+	"strconv"
 	"strings"
 
 	"github.com/goccy/go-yaml"
@@ -47,7 +48,11 @@ func Load(ctx context.Context, source Source) (*latest.Config, error) {
 
 	oldConfig, err := parseCurrentVersion(data, raw.Version)
 	if err != nil {
-		return nil, fmt.Errorf("parsing config file\n%s", yaml.FormatError(err, true, true))
+		msg := yaml.FormatError(err, true, true)
+		if hint := newerVersionHint(data, raw.Version, err); hint != "" {
+			msg += "\n" + hint
+		}
+		return nil, fmt.Errorf("parsing config file\n%s", msg)
 	}
 
 	config, err := migrateToLatestConfig(oldConfig, data)
@@ -172,6 +177,42 @@ func parseCurrentVersion(data []byte, version string) (any, error) {
 	return parser(data)
 }
 
+// newerVersionHint returns a user-facing hint when a strict-parse failure is
+// caused by a key that a newer schema version accepts. It tries the parsers
+// for every version above the declared one, in order, and points the user at
+// the smallest version that parses the config successfully. Best-effort: a
+// newer version may accept the config for unrelated reasons (laxer schema),
+// so the original unknown-field error is always shown before the hint.
+func newerVersionHint(data []byte, version string, parseErr error) string {
+	var unknownField *yaml.UnknownFieldError
+	if !errors.As(parseErr, &unknownField) {
+		return ""
+	}
+
+	current, err := strconv.Atoi(version)
+	if err != nil {
+		return ""
+	}
+
+	parsers, _ := versions()
+	var newer []int
+	for v := range parsers {
+		if n, err := strconv.Atoi(v); err == nil && n > current {
+			newer = append(newer, n)
+		}
+	}
+	slices.Sort(newer)
+
+	for _, n := range newer {
+		v := strconv.Itoa(n)
+		if _, err := parsers[v](data); err == nil {
+			return fmt.Sprintf("hint: this key is supported by config version %s; update the top-level 'version' field (currently %s)", v, version)
+		}
+	}
+
+	return ""
+}
+
 func migrateToLatestConfig(c any, raw []byte) (latest.Config, error) {
 	var err error
 

pkg/config/config_test.go

@@ -979,3 +979,57 @@ func TestProviders_Validation(t *testing.T) {
 		})
 	}
 }
+
+func TestLoadUnknownKeyFromNewerVersionHint(t *testing.T) {
+	t.Parallel()
+
+	// instruction_file was introduced in version 11.
+	cfgStr := `version: "10"
+agents:
+  root:
+    model: openai/gpt-4o
+    instruction_file: prompt.md
+`
+	_, err := Load(t.Context(), NewBytesSource("test.yaml", []byte(cfgStr)))
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), `unknown field "instruction_file"`)
+	assert.Contains(t, err.Error(), "supported by config version 11")
+	assert.Contains(t, err.Error(), "currently 10")
+}
+
+func TestLoadUnknownKeyNoNewerVersionNoHint(t *testing.T) {
+	t.Parallel()
+
+	cfgStr := `version: "` + latest.Version + `"
+agents:
+  root:
+    model: openai/gpt-4o
+    instruction: test
+    not_a_real_key: true
+`
+	_, err := Load(t.Context(), NewBytesSource("test.yaml", []byte(cfgStr)))
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), `unknown field "not_a_real_key"`)
+	assert.NotContains(t, err.Error(), "hint:")
+}
+
+func TestLoadNewerVersionHintNumericOrdering(t *testing.T) {
+	t.Parallel()
+
+	// force_handoff was introduced in version 10. Declaring version "2" pins
+	// two behaviors: versions compare numerically ("10" > "2" despite
+	// lexicographic order) and the smallest accepting version wins (10, not
+	// 11 or 12).
+	cfgStr := `version: "2"
+agents:
+  root:
+    model: openai/gpt-4o
+    instruction: test
+    force_handoff: root
+`
+	_, err := Load(t.Context(), NewBytesSource("test.yaml", []byte(cfgStr)))
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), `unknown field "force_handoff"`)
+	assert.Contains(t, err.Error(), "supported by config version 10")
+	assert.Contains(t, err.Error(), "currently 2")
+}