Agent Executor (AX) is Google's open agentic orchestration runtime
Go
runner: ignore unknown fields in specs from the control plane (#506)
Grant McCloskey0f085aa063db
diff --git a/cmd/ax-task-runner/main.go b/cmd/ax-task-runner/main.goindex e9e0d9c..66cec43 100644--- a/cmd/ax-task-runner/main.go+++ b/cmd/ax-task-runner/main.go@@ -32,6 +32,7 @@ import ("github.com/google/ax/pkg/apis/v1alpha1""github.com/google/ax/runner"+ "google.golang.org/protobuf/proto""gopkg.in/yaml.v3")@@ -73,8 +74,10 @@ func main() {}// loadSpec decodes YAML into out from file when set, otherwise from the named-// environment variable. It is not an error for neither to be present.-func loadSpec(file, envVar string, out any) error {+// environment variable. It is not an error for neither to be present, or for+// the YAML to be blank. Unknown fields are ignored, so a runner image keeps+// working with a newer control plane.+func loadSpec(file, envVar string, out proto.Message) error {var raw []byteswitch {case file != "":@@ -88,7 +91,14 @@ func loadSpec(file, envVar string, out any) error {default:return nil}- if err := yaml.Unmarshal(raw, out); err != nil {+ var node yaml.Node+ if err := yaml.Unmarshal(raw, &node); err != nil {+ return fmt.Errorf("parsing %T: %w", out, err)+ }+ if len(node.Content) == 0 || node.Content[0].ShortTag() == "!!null" {+ return nil+ }+ if err := v1alpha1.UnmarshalYAMLLenient(node.Content[0], out); err != nil {return fmt.Errorf("parsing %T: %w", out, err)}return nildiff --git a/cmd/ax-task-runner/main_test.go b/cmd/ax-task-runner/main_test.gonew file mode 100644index 0000000..e0cbb03--- /dev/null+++ b/cmd/ax-task-runner/main_test.go@@ -0,0 +1,56 @@+// Copyright 2026 Google LLC+//+// Licensed under the Apache License, Version 2.0 (the "License");+// you may not use this file except in compliance with the License.+// You may obtain a copy of the License at+//+// http://www.apache.org/licenses/LICENSE-2.0+//+// Unless required by applicable law or agreed to in writing, software+// distributed under the License is distributed on an "AS IS" BASIS,+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+// See the License for the specific language governing permissions and+// limitations under the License.++package main++import (+ "testing"++ "github.com/google/ax/pkg/apis/v1alpha1"+)++// A newer ax-server may send Task and Workspace fields this runner doesn't+// know; they must not stop the task from starting.+func TestLoadSpec_IgnoresUnknownFields(t *testing.T) {+ t.Setenv("AX_TASK_YAML", "metadata:\n name: t\nspec:\n image: img\n egress:\n - host: example.com\n")+ var task v1alpha1.Task+ if err := loadSpec("", "AX_TASK_YAML", &task); err != nil {+ t.Fatalf("loadSpec: %v", err)+ }+ if task.GetMetadata().GetName() != "t" || task.GetSpec().GetImage() != "img" {+ t.Errorf("unexpected task %v", &task)+ }+}++func TestLoadSpec_Empty(t *testing.T) {+ t.Setenv("AX_TASK_YAML", "\n")+ var task v1alpha1.Task+ if err := loadSpec("", "AX_TASK_YAML", &task); err != nil {+ t.Fatalf("loadSpec: %v", err)+ }+ if task.GetMetadata() != nil {+ t.Errorf("expected no task, got %v", &task)+ }+}++func TestLoadSpec_WorkspaceIgnoresUnknownFields(t *testing.T) {+ t.Setenv("AX_WORKSPACE_YAML", "metadata:\n name: ws\nspec:\n fieldFromTheFuture: 1\n")+ var ws v1alpha1.Workspace+ if err := loadSpec("", "AX_WORKSPACE_YAML", &ws); err != nil {+ t.Fatalf("loadSpec: %v", err)+ }+ if ws.GetMetadata().GetName() != "ws" {+ t.Errorf("unexpected workspace %v", &ws)+ }+}diff --git a/pkg/apis/v1alpha1/types.go b/pkg/apis/v1alpha1/types.goindex 5b98965..2138223 100644--- a/pkg/apis/v1alpha1/types.go+++ b/pkg/apis/v1alpha1/types.go@@ -59,6 +59,9 @@ const (var (protoMarshal = protojson.MarshalOptions{}protoUnmarshal = protojson.UnmarshalOptions{} // unknown fields are errors+ // protoUnmarshalLenient is for specs the control plane hands to a runner,+ // which may come from a newer control plane than the runner image.+ protoUnmarshalLenient = protojson.UnmarshalOptions{DiscardUnknown: true})// normalizer rewrites a generically decoded document in place so legacy shapes@@ -74,6 +77,25 @@ func marshalYAML(m proto.Message) (any, error) {}func unmarshalYAML(value *yaml.Node, m proto.Message, normalize normalizer) error {+ return unmarshalYAMLWith(value, m, normalize, protoUnmarshal)+}++// UnmarshalYAMLLenient decodes a Task, Workspace or Model like their+// UnmarshalYAML methods but ignores fields it doesn't know. Runners use it for+// the specs the control plane passes them, so a runner image keeps working+// when a newer control plane adds fields it doesn't use.+func UnmarshalYAMLLenient(value *yaml.Node, m proto.Message) error {+ var normalize normalizer+ switch m.(type) {+ case *Workspace:+ normalize = normalizeWorkspace+ case *Model:+ normalize = normalizeModel+ }+ return unmarshalYAMLWith(value, m, normalize, protoUnmarshalLenient)+}++func unmarshalYAMLWith(value *yaml.Node, m proto.Message, normalize normalizer, opts protojson.UnmarshalOptions) error {var doc anyif err := value.Decode(&doc); err != nil {return err@@ -85,7 +107,7 @@ func unmarshalYAML(value *yaml.Node, m proto.Message, normalize normalizer) erroif err != nil {return fmt.Errorf("converting yaml to json: %w", err)}- return protoUnmarshal.Unmarshal(data, m)+ return opts.Unmarshal(data, m)}// jsonToYAMLNode converts a JSON document into a yaml.Node tree, preservingdiff --git a/pkg/apis/v1alpha1/types_test.go b/pkg/apis/v1alpha1/types_test.goindex e6fefbe..48a6d10 100644--- a/pkg/apis/v1alpha1/types_test.go+++ b/pkg/apis/v1alpha1/types_test.go@@ -559,3 +559,39 @@ func TestValidateWorkspace_Files(t *testing.T) {t.Errorf("expected path is required error, got %v", err)}}++func TestUnmarshalYAMLLenient_IgnoresUnknownFields(t *testing.T) {+ doc := "metadata:\n name: t\n atespace: default\nspec:\n image: img\n fieldFromTheFuture: 1\n"+ var node yaml.Node+ if err := yaml.Unmarshal([]byte(doc), &node); err != nil {+ t.Fatal(err)+ }++ var strict v1alpha1.Task+ if err := node.Decode(&strict); err == nil {+ t.Fatal("strict decoding should reject an unknown field")+ }++ var lenient v1alpha1.Task+ if err := v1alpha1.UnmarshalYAMLLenient(&node, &lenient); err != nil {+ t.Fatalf("lenient decoding failed: %v", err)+ }+ if lenient.GetSpec().GetImage() != "img" {+ t.Errorf("image = %q, want img", lenient.GetSpec().GetImage())+ }+}++func TestUnmarshalYAMLLenient_NormalizesWorkspace(t *testing.T) {+ doc := "metadata:\n name: ws\nspec:\n fieldFromTheFuture: true\n mcp:\n - name: srv\n"+ var node yaml.Node+ if err := yaml.Unmarshal([]byte(doc), &node); err != nil {+ t.Fatal(err)+ }+ var ws v1alpha1.Workspace+ if err := v1alpha1.UnmarshalYAMLLenient(&node, &ws); err != nil {+ t.Fatalf("lenient decoding failed: %v", err)+ }+ if got := ws.GetSpec().GetMcp().GetServers(); len(got) != 1 || got[0].GetName() != "srv" {+ t.Errorf("mcp servers = %v, want one named srv", got)+ }+}