Merge pull request #88 from LAA-Software-Engineering/feat/spec-defaults-runtime-76

feat(spec): apply defaults.runtime via Agent/Workflow spec.runtime (MVP)

Author: leo-aa88

docs/EXAMPLES.md

@@ -39,6 +39,8 @@ Sections **2–3** mirror what `init` creates. **Section 4** is a separate **`gp
 
 `spec.imports` lists YAML files relative to the project root. `defaults.model` uses the form **`namespace/model_id`**, where **`namespace`** matches a key under `spec.providers.models`.
 
+Optional **`defaults.runtime`** sets where agents and workflows run in MVP: only **`local`** is valid (or omit for implicit local). Resources that omit **`spec.runtime`** inherit this value when the merged project graph is normalized.
+
 ```yaml
 apiVersion: agentic.dev/v0
 kind: Project
@@ -52,6 +54,7 @@ spec:
   defaults:
     policy: default
     model: mock/gpt-4
+    runtime: local
   providers:
     models:
       mock:

examples/example1/project.yaml

@@ -11,6 +11,7 @@ spec:
   defaults:
     policy: default
     model: openai/gpt-4o-mini
+    runtime: local
   providers:
     models:
       mock:

internal/spec/defaults.go

@@ -3,8 +3,7 @@ package spec
 import "strings"
 
 // projectDefaults holds trimmed Project.spec.defaults values (design doc §7.1).
-// Runtime is included for API symmetry with the YAML schema; see NormalizeProjectGraph
-// for which fields are applied to MVP resource specs.
+// Runtime is copied onto Agent and Workflow specs when they omit spec.runtime (issue #76).
 type projectDefaults struct {
 	Runtime string
 	Model   string

internal/spec/kinds.go

@@ -49,6 +49,7 @@ type ProjectTracesConfig struct {
 type AgentSpec struct {
 	Description  string            `yaml:"description,omitempty" json:"description,omitempty"`
 	Model        string            `yaml:"model,omitempty" json:"model,omitempty"`
+	Runtime      string            `yaml:"runtime,omitempty" json:"runtime,omitempty"`
 	Instructions string            `yaml:"instructions,omitempty" json:"instructions,omitempty"`
 	Tools        []string          `yaml:"tools,omitempty" json:"tools,omitempty"`
 	Policy       string            `yaml:"policy,omitempty" json:"policy,omitempty"`
@@ -109,6 +110,7 @@ type ToolRetry struct {
 
 type WorkflowSpec struct {
 	Description string           `yaml:"description,omitempty" json:"description,omitempty"`
+	Runtime     string           `yaml:"runtime,omitempty" json:"runtime,omitempty"`
 	Trigger     *WorkflowTrigger `yaml:"trigger,omitempty" json:"trigger,omitempty"`
 	Input       *WorkflowInput   `yaml:"input,omitempty" json:"input,omitempty"`
 	Policy      string           `yaml:"policy,omitempty" json:"policy,omitempty"`

internal/spec/normalize.go

@@ -6,37 +6,34 @@ import "strings"
 // fields and performs trivial string canonicalization (trim surrounding ASCII space).
 //
 // Default application (§7.1 → effective config):
-//   - Agent.spec.model  ← defaults.model when the agent omits model (empty / whitespace-only).
-//   - Agent.spec.policy ← defaults.policy when the agent omits policy.
-//   - Workflow.spec.policy ← defaults.policy when the workflow omits policy.
-//
-// defaults.runtime: MVP Agent and Workflow specs have no runtime field (§7.2, §7.4), so
-// this value is not copied onto resources here; a future loader may attach it when a
-// target field exists.
+//   - Agent.spec.model    ← defaults.model when the agent omits model (empty / whitespace-only).
+//   - Agent.spec.policy   ← defaults.policy when the agent omits policy.
+//   - Agent.spec.runtime  ← defaults.runtime when the agent omits runtime (issue #76).
+//   - Workflow.spec.policy  ← defaults.policy when the workflow omits policy.
+//   - Workflow.spec.runtime ← defaults.runtime when the workflow omits runtime (issue #76).
 //
 // Environment overrides are out of scope (issue #4). Mutates graphs in place.
 func NormalizeProjectGraph(g *ProjectGraph) {
 	if g == nil {
 		return
 	}
 	def := readProjectDefaults(g)
-	_ = def.Runtime // reserved until a spec field consumes it
 
 	for _, a := range g.Agents {
 		if a == nil {
 			continue
 		}
-		normalizeAgentSpec(&a.Spec, def.Model, def.Policy)
+		normalizeAgentSpec(&a.Spec, def.Model, def.Policy, def.Runtime)
 	}
 	for _, w := range g.Workflows {
 		if w == nil {
 			continue
 		}
-		normalizeWorkflowSpec(&w.Spec, def.Policy)
+		normalizeWorkflowSpec(&w.Spec, def.Policy, def.Runtime)
 	}
 }
 
-func normalizeAgentSpec(spec *AgentSpec, defModel, defPolicy string) {
+func normalizeAgentSpec(spec *AgentSpec, defModel, defPolicy, defRuntime string) {
 	if spec == nil {
 		return
 	}
@@ -52,9 +49,14 @@ func normalizeAgentSpec(spec *AgentSpec, defModel, defPolicy string) {
 	} else {
 		spec.Policy = strings.TrimSpace(spec.Policy)
 	}
+	if defRuntime != "" && isOmitted(spec.Runtime) {
+		spec.Runtime = defRuntime
+	} else {
+		spec.Runtime = strings.TrimSpace(spec.Runtime)
+	}
 }
 
-func normalizeWorkflowSpec(spec *WorkflowSpec, defPolicy string) {
+func normalizeWorkflowSpec(spec *WorkflowSpec, defPolicy, defRuntime string) {
 	if spec == nil {
 		return
 	}
@@ -63,6 +65,11 @@ func normalizeWorkflowSpec(spec *WorkflowSpec, defPolicy string) {
 	} else {
 		spec.Policy = strings.TrimSpace(spec.Policy)
 	}
+	if defRuntime != "" && isOmitted(spec.Runtime) {
+		spec.Runtime = defRuntime
+	} else {
+		spec.Runtime = strings.TrimSpace(spec.Runtime)
+	}
 }
 
 func isOmitted(s string) bool {

internal/spec/normalize_test.go

@@ -34,6 +34,44 @@ func TestNormalizeProjectGraph_agentGetsDefaultModel(t *testing.T) {
 	}
 }
 
+func TestNormalizeProjectGraph_agentGetsDefaultRuntime(t *testing.T) {
+	g := &ProjectGraph{
+		Spec: ProjectSpec{
+			Defaults: &ProjectDefaults{Runtime: "local"},
+		},
+		Agents: map[string]*AgentResource{
+			"a": {
+				Kind:     KindAgent,
+				Metadata: Metadata{Name: "a"},
+				Spec:     AgentSpec{Model: "mock/x"},
+			},
+		},
+	}
+	NormalizeProjectGraph(g)
+	if got := g.Agents["a"].Spec.Runtime; got != "local" {
+		t.Fatalf("Runtime = %q, want local", got)
+	}
+}
+
+func TestNormalizeProjectGraph_workflowGetsDefaultRuntime(t *testing.T) {
+	g := &ProjectGraph{
+		Spec: ProjectSpec{
+			Defaults: &ProjectDefaults{Runtime: "local"},
+		},
+		Workflows: map[string]*WorkflowResource{
+			"w": {
+				Kind:     KindWorkflow,
+				Metadata: Metadata{Name: "w"},
+				Spec:     WorkflowSpec{Policy: "p"},
+			},
+		},
+	}
+	NormalizeProjectGraph(g)
+	if got := g.Workflows["w"].Spec.Runtime; got != "local" {
+		t.Fatalf("Runtime = %q, want local", got)
+	}
+}
+
 func TestNormalizeProjectGraph_workflowGetsDefaultPolicy(t *testing.T) {
 	g := &ProjectGraph{
 		Spec: ProjectSpec{
@@ -88,6 +126,39 @@ func TestNormalizeProjectGraph_idempotent(t *testing.T) {
 	}
 }
 
+func TestNormalizeProjectGraph_preservesExplicitRuntimeOverDefault(t *testing.T) {
+	g := &ProjectGraph{
+		Spec: ProjectSpec{
+			Defaults: &ProjectDefaults{Runtime: "local"},
+		},
+		Agents: map[string]*AgentResource{
+			"a": {Spec: AgentSpec{Runtime: "edge"}},
+		},
+	}
+	NormalizeProjectGraph(g)
+	if got := g.Agents["a"].Spec.Runtime; got != "edge" {
+		t.Fatalf("Runtime = %q, want edge (explicit value must not be replaced by defaults)", got)
+	}
+}
+
+func TestNormalizeProjectGraph_trimsWorkflowRuntimeWhenSet(t *testing.T) {
+	g := &ProjectGraph{
+		Spec: ProjectSpec{
+			Defaults: &ProjectDefaults{Runtime: "local"},
+		},
+		Workflows: map[string]*WorkflowResource{
+			"w": {
+				Kind: KindWorkflow,
+				Spec: WorkflowSpec{Runtime: "  local  "},
+			},
+		},
+	}
+	NormalizeProjectGraph(g)
+	if got := g.Workflows["w"].Spec.Runtime; got != "local" {
+		t.Fatalf("Runtime = %q, want trimmed local", got)
+	}
+}
+
 func TestNormalizeProjectGraph_doesNotOverrideExplicitModel(t *testing.T) {
 	g := &ProjectGraph{
 		Spec: ProjectSpec{

internal/spec/validator.go

@@ -23,6 +23,7 @@ func ValidateProjectGraph(g *ProjectGraph, projectRoot string) error {
 
 	var errs []error
 	errs = append(errs, validateMetadataKeys(g)...)
+	errs = append(errs, validateMVPRuntimes(g)...)
 	errs = append(errs, validateToolSpecs(g)...)
 	errs = append(errs, validatePolicySpecs(g)...)
 	errs = append(errs, validateAgentSpecs(g)...)
@@ -107,6 +108,34 @@ func metaName(v any) string {
 	}
 }
 
+// validateMVPRuntimes rejects non-local explicit runtimes (design doc §7.1, §16 MVP; issue #76).
+// Empty means implicit local; only "local" is allowed when set.
+func validateMVPRuntimes(g *ProjectGraph) []error {
+	var errs []error
+	if g.Spec.Defaults != nil {
+		if r := strings.TrimSpace(g.Spec.Defaults.Runtime); r != "" && r != "local" {
+			errs = append(errs, fmt.Errorf("Project: defaults.runtime %q is not supported in MVP (use \"local\" or omit)", r))
+		}
+	}
+	for name, ar := range g.Agents {
+		if ar == nil {
+			continue
+		}
+		if r := strings.TrimSpace(ar.Spec.Runtime); r != "" && r != "local" {
+			errs = append(errs, fmt.Errorf("Agent/%s: spec.runtime %q is not supported in MVP (use \"local\" or omit)", name, r))
+		}
+	}
+	for name, wr := range g.Workflows {
+		if wr == nil {
+			continue
+		}
+		if r := strings.TrimSpace(wr.Spec.Runtime); r != "" && r != "local" {
+			errs = append(errs, fmt.Errorf("Workflow/%s: spec.runtime %q is not supported in MVP (use \"local\" or omit)", name, r))
+		}
+	}
+	return errs
+}
+
 func validateToolSpecs(g *ProjectGraph) []error {
 	var errs []error
 	for name, tr := range g.Tools {

internal/spec/validator_test.go

@@ -176,3 +176,72 @@ func TestValidateProjectGraph_duplicateApprovalActions(t *testing.T) {
 		t.Fatalf("expected duplicate approvals error, got %v", err)
 	}
 }
+
+func TestValidateProjectGraph_defaultsRuntimeUnknown(t *testing.T) {
+	g := &ProjectGraph{
+		Spec: ProjectSpec{
+			Defaults: &ProjectDefaults{Runtime: "k8s"},
+		},
+	}
+	err := ValidateProjectGraph(g, t.TempDir())
+	if err == nil || !strings.Contains(err.Error(), `defaults.runtime "k8s"`) {
+		t.Fatalf("expected defaults.runtime error, got %v", err)
+	}
+}
+
+func TestValidateProjectGraph_agentRuntimeUnknown(t *testing.T) {
+	g := &ProjectGraph{
+		Agents: map[string]*AgentResource{
+			"a": {
+				Kind:     KindAgent,
+				Metadata: Metadata{Name: "a"},
+				Spec:     AgentSpec{Runtime: "remote"},
+			},
+		},
+	}
+	err := ValidateProjectGraph(g, t.TempDir())
+	if err == nil || !strings.Contains(err.Error(), `Agent/a: spec.runtime "remote"`) {
+		t.Fatalf("expected agent runtime error, got %v", err)
+	}
+}
+
+func TestValidateProjectGraph_workflowRuntimeUnknown(t *testing.T) {
+	g := &ProjectGraph{
+		Workflows: map[string]*WorkflowResource{
+			"w": {
+				Kind:     KindWorkflow,
+				Metadata: Metadata{Name: "w"},
+				Spec:     WorkflowSpec{Runtime: "lambda"},
+			},
+		},
+	}
+	err := ValidateProjectGraph(g, t.TempDir())
+	if err == nil || !strings.Contains(err.Error(), `Workflow/w: spec.runtime "lambda"`) {
+		t.Fatalf("expected workflow runtime error, got %v", err)
+	}
+}
+
+func TestValidateProjectGraph_runtimeLocalAccepted(t *testing.T) {
+	g := &ProjectGraph{
+		Spec: ProjectSpec{
+			Defaults: &ProjectDefaults{Runtime: "local"},
+		},
+		Agents: map[string]*AgentResource{
+			"a": {
+				Kind:     KindAgent,
+				Metadata: Metadata{Name: "a"},
+				Spec:     AgentSpec{Runtime: "local"},
+			},
+		},
+		Workflows: map[string]*WorkflowResource{
+			"w": {
+				Kind:     KindWorkflow,
+				Metadata: Metadata{Name: "w"},
+				Spec:     WorkflowSpec{Runtime: "local"},
+			},
+		},
+	}
+	if err := ValidateProjectGraph(g, t.TempDir()); err != nil {
+		t.Fatal(err)
+	}
+}