fix: tighten template control validation ergonomics

Author: lan17

models/src/agent_control_models/controls.py

@@ -5,7 +5,7 @@
 import re
 from collections.abc import Iterator
 from dataclasses import dataclass
-from typing import Annotated, Any, Literal, Self, cast
+from typing import Annotated, Any, Literal, Self
 from uuid import uuid4
 
 import re2
@@ -871,13 +871,6 @@ def observability_identity(self) -> ControlObservabilityIdentity:
             all_selector_paths=all_selector_paths,
         )
 
-    def to_control_definition(self) -> ControlDefinition:
-        """Promote a runtime control to the full public model when needed."""
-        return ControlDefinition.model_validate(
-            cast(dict[str, JSONValue], self.model_dump(mode="python"))
-        )
-
-
 class EvaluatorResult(BaseModel):
     """Result from a control evaluator.
 

models/src/agent_control_models/server.py

@@ -16,6 +16,20 @@ def _strip_slug_name(v: str) -> str:
 
 _CONTROL_DEFINITION_ADAPTER = TypeAdapter(ControlDefinition)
 _TEMPLATE_CONTROL_INPUT_ADAPTER = TypeAdapter(TemplateControlInput)
+_RAW_CONTROL_INPUT_FIELDS = frozenset(
+    {
+        "description",
+        "enabled",
+        "execution",
+        "scope",
+        "condition",
+        "action",
+        "tags",
+        # Legacy flat leaf fields still accepted for raw controls.
+        "selector",
+        "evaluator",
+    }
+)
 
 
 def _parse_control_input(v: Any) -> Any:
@@ -30,6 +44,12 @@ def _parse_control_input(v: Any) -> Any:
         return v
 
     if v.get("template") is not None:
+        mixed_fields = sorted(field for field in v if field in _RAW_CONTROL_INPUT_FIELDS)
+        if mixed_fields:
+            raise ValueError(
+                "Template-backed control input cannot mix template fields with rendered control "
+                f"fields. Remove raw fields: {', '.join(mixed_fields)}."
+            )
         return _TEMPLATE_CONTROL_INPUT_ADAPTER.validate_python(v)
     return _CONTROL_DEFINITION_ADAPTER.validate_python(v)
 

models/tests/test_control_templates.py

@@ -58,6 +58,28 @@ def test_control_definition_requires_template_fields_together() -> None:
         )
 
 
+def test_control_definition_rejects_template_values_without_template() -> None:
+    with pytest.raises(
+        ValidationError,
+        match="template and template_values must both be present or both absent",
+    ):
+        ControlDefinition.model_validate(
+            {
+                "execution": "server",
+                "scope": {"step_types": ["llm"], "stages": ["pre"]},
+                "condition": {
+                    "selector": {"path": "input"},
+                    "evaluator": {
+                        "name": "regex",
+                        "config": {"pattern": "ok"},
+                    },
+                },
+                "action": {"decision": "deny"},
+                "template_values": {"pattern": "hello"},
+            }
+        )
+
+
 def test_template_definition_rejects_invalid_parameter_name() -> None:
     with pytest.raises(
         ValidationError,
@@ -91,7 +113,13 @@ def test_create_control_request_parses_template_payload_as_template_input() -> N
 
 
 def test_create_control_request_rejects_mixed_raw_and_template_payload() -> None:
-    with pytest.raises(ValidationError):
+    with pytest.raises(
+        ValidationError,
+        match=(
+            "Template-backed control input cannot mix template fields with rendered "
+            "control fields"
+        ),
+    ):
         CreateControlRequest.model_validate(
             {
                 "name": "template-control",
@@ -130,6 +158,26 @@ def test_control_definition_can_round_trip_to_template_control_input() -> None:
     assert template_input.template_values == {"pattern": "hello"}
 
 
+def test_control_definition_to_template_control_input_rejects_raw_control() -> None:
+    control = ControlDefinition.model_validate(
+        {
+            "execution": "server",
+            "scope": {"step_types": ["llm"], "stages": ["pre"]},
+            "condition": {
+                "selector": {"path": "input"},
+                "evaluator": {
+                    "name": "regex",
+                    "config": {"pattern": "hello"},
+                },
+            },
+            "action": {"decision": "deny"},
+        }
+    )
+
+    with pytest.raises(ValueError, match="not template-backed"):
+        control.to_template_control_input()
+
+
 def test_control_definition_runtime_ignores_template_metadata() -> None:
     runtime_control = ControlDefinitionRuntime.model_validate(
         {

sdks/python/tests/test_controls_api.py

@@ -109,6 +109,90 @@ async def test_render_control_template_calls_preview_endpoint() -> None:
     )
 
 
+@pytest.mark.asyncio
+async def test_validate_control_data_accepts_template_control_input() -> None:
+    response = Mock()
+    response.raise_for_status = Mock()
+    response.json = Mock(return_value={"success": True})
+    client = SimpleNamespace(http_client=SimpleNamespace(post=AsyncMock(return_value=response)))
+    template_input = TemplateControlInput.model_validate(
+        {
+            "template": {
+                "parameters": {
+                    "pattern": {
+                        "type": "regex_re2",
+                        "label": "Pattern",
+                    }
+                },
+                "definition_template": {
+                    "execution": "server",
+                    "scope": {"step_types": ["llm"], "stages": ["pre"]},
+                    "condition": {
+                        "selector": {"path": "input"},
+                        "evaluator": {
+                            "name": "regex",
+                            "config": {"pattern": {"$param": "pattern"}},
+                        },
+                    },
+                    "action": {"decision": "deny"},
+                },
+            },
+            "template_values": {"pattern": "hello"},
+        }
+    )
+
+    await agent_control.controls.validate_control_data(client, template_input)
+
+    client.http_client.post.assert_awaited_once()
+    _, kwargs = client.http_client.post.await_args
+    assert kwargs["json"]["data"]["template_values"]["pattern"] == "hello"
+    assert kwargs["json"] == {
+        "data": {
+            "template": kwargs["json"]["data"]["template"],
+            "template_values": {"pattern": "hello"},
+        }
+    }
+
+
+@pytest.mark.asyncio
+async def test_set_control_data_accepts_template_control_input() -> None:
+    response = Mock()
+    response.raise_for_status = Mock()
+    response.json = Mock(return_value={"success": True})
+    client = SimpleNamespace(http_client=SimpleNamespace(put=AsyncMock(return_value=response)))
+    template_input = TemplateControlInput.model_validate(
+        {
+            "template": {
+                "parameters": {
+                    "pattern": {
+                        "type": "regex_re2",
+                        "label": "Pattern",
+                    }
+                },
+                "definition_template": {
+                    "execution": "server",
+                    "scope": {"step_types": ["llm"], "stages": ["pre"]},
+                    "condition": {
+                        "selector": {"path": "input"},
+                        "evaluator": {
+                            "name": "regex",
+                            "config": {"pattern": {"$param": "pattern"}},
+                        },
+                    },
+                    "action": {"decision": "deny"},
+                },
+            },
+            "template_values": {"pattern": "hello"},
+        }
+    )
+
+    await agent_control.controls.set_control_data(client, 123, template_input)
+
+    client.http_client.put.assert_awaited_once()
+    _, kwargs = client.http_client.put.await_args
+    assert kwargs["json"]["data"]["template_values"]["pattern"] == "hello"
+
+
 def test_to_template_control_input_reshapes_stored_control_data() -> None:
     template_input = agent_control.controls.to_template_control_input(
         {
@@ -148,3 +232,21 @@ def test_to_template_control_input_reshapes_stored_control_data() -> None:
 
     assert isinstance(template_input, TemplateControlInput)
     assert template_input.template_values == {"pattern": "hello"}
+
+
+def test_to_template_control_input_rejects_raw_control_data() -> None:
+    with pytest.raises(ValueError, match="not template-backed"):
+        agent_control.controls.to_template_control_input(
+            {
+                "execution": "server",
+                "scope": {"step_types": ["llm"], "stages": ["pre"]},
+                "condition": {
+                    "selector": {"path": "input"},
+                    "evaluator": {
+                        "name": "regex",
+                        "config": {"pattern": "hello"},
+                    },
+                },
+                "action": {"decision": "deny"},
+            }
+        )

server/src/agent_control_server/endpoints/controls.py

@@ -528,11 +528,9 @@ async def set_control_data(
     current_template_backed = _is_template_backed_payload(control.data)
     if isinstance(request.data, TemplateControlInput):
         current_enabled = True
-        if control.data:
-            try:
-                current_enabled = ControlDefinition.model_validate(control.data).enabled
-            except ValidationError:
-                current_enabled = True
+        if isinstance(control.data, dict):
+            raw_enabled = control.data.get("enabled", True)
+            current_enabled = raw_enabled if type(raw_enabled) is bool else True
         control_def = await _render_and_validate_template_input(
             request.data,
             db=db,

server/src/agent_control_server/services/control_templates.py

@@ -297,9 +297,27 @@ def _render_json_value(
                     message=f"Template references undefined parameter '{parameter_name}'.",
                 )
 
+            parameter_definition = template.parameters[parameter_name]
+            if (
+                not parameter_definition.required
+                and _parameter_default(parameter_definition) is _TEMPLATE_VALUE_MISSING
+            ):
+                raise _render_error(
+                    detail=(
+                        f"Template parameter '{parameter_name}' is optional but referenced in "
+                        "definition_template without a default value"
+                    ),
+                    field=f"template.parameters.{parameter_name}",
+                    code="optional_referenced_parameter_requires_default",
+                    message=(
+                        f"Optional template parameter '{parameter_definition.label}' is "
+                        "referenced in the template and must define a default value or be "
+                        "marked required."
+                    ),
+                )
+
             resolved_value = resolved_values[parameter_name]
             if resolved_value is _TEMPLATE_VALUE_MISSING:
-                parameter_definition = template.parameters[parameter_name]
                 raise _parameter_error(
                     parameter_name,
                     parameter_definition,

server/tests/test_control_templates.py

@@ -669,6 +669,29 @@ def test_render_control_template_maps_invalid_regex_parameter(client: TestClient
     )
 
 
+def test_render_control_template_rejects_optional_referenced_parameter_without_default(
+    client: TestClient,
+) -> None:
+    payload = _template_payload()
+    payload["template"] = deepcopy(payload["template"])
+    payload["template"]["parameters"]["step_name"] = {  # type: ignore[index]
+        "type": "string",
+        "label": "Step Name",
+        "required": False,
+    }
+
+    response = client.post("/api/v1/control-templates/render", json=payload)
+
+    assert response.status_code == 422
+    body = response.json()
+    assert body["error_code"] == "TEMPLATE_RENDER_ERROR"
+    assert any(
+        err.get("field") == "template.parameters.step_name"
+        and err.get("code") == "optional_referenced_parameter_requires_default"
+        for err in body.get("errors", [])
+    )
+
+
 def test_render_control_template_rejects_malformed_param_binding(client: TestClient) -> None:
     payload = _template_payload()
     payload["template"] = deepcopy(payload["template"])