fix: tighten template control API contracts

Author: lan17

models/src/agent_control_models/errors.py

@@ -68,6 +68,7 @@ class ErrorCode(StrEnum):
     CONTROL_NAME_CONFLICT = "CONTROL_NAME_CONFLICT"
     EVALUATOR_NAME_CONFLICT = "EVALUATOR_NAME_CONFLICT"
     CONTROL_IN_USE = "CONTROL_IN_USE"
+    CONTROL_TEMPLATE_CONFLICT = "CONTROL_TEMPLATE_CONFLICT"
     EVALUATOR_IN_USE = "EVALUATOR_IN_USE"
     SCHEMA_INCOMPATIBLE = "SCHEMA_INCOMPATIBLE"
 
@@ -370,6 +371,7 @@ def make_error_type(error_code: ErrorCode) -> str:
     ErrorCode.CONTROL_NAME_CONFLICT: "Control Name Already Exists",
     ErrorCode.EVALUATOR_NAME_CONFLICT: "Evaluator Name Conflict",
     ErrorCode.CONTROL_IN_USE: "Control In Use",
+    ErrorCode.CONTROL_TEMPLATE_CONFLICT: "Control Template Conflict",
     ErrorCode.EVALUATOR_IN_USE: "Evaluator In Use",
     ErrorCode.SCHEMA_INCOMPATIBLE: "Schema Incompatible",
     # Validation errors

models/src/agent_control_models/server.py

@@ -1,7 +1,7 @@
 from enum import StrEnum
 from typing import Annotated, Any
 
-from pydantic import BeforeValidator, Field, StringConstraints, TypeAdapter
+from pydantic import BeforeValidator, ConfigDict, Field, StringConstraints, TypeAdapter
 
 from .agent import Agent, StepSchema
 from .base import BaseModel
@@ -346,6 +346,8 @@ class ValidateControlDataResponse(BaseModel):
 class RenderControlTemplateRequest(BaseModel):
     """Request to render a template-backed control without persisting it."""
 
+    model_config = ConfigDict(extra="forbid")
+
     template: TemplateDefinition = Field(..., description="Template definition to render")
     template_values: dict[str, TemplateValue] = Field(
         default_factory=dict,

server/src/agent_control_server/endpoints/controls.py

@@ -541,7 +541,7 @@ async def set_control_data(
     else:
         if current_template_backed:
             raise ConflictError(
-                error_code=ErrorCode.CONTROL_IN_USE,
+                error_code=ErrorCode.CONTROL_TEMPLATE_CONFLICT,
                 detail="Template-backed controls cannot be updated with raw control data in v1",
                 resource="Control",
                 resource_id=str(control_id),

server/src/agent_control_server/services/control_templates.py

@@ -95,6 +95,8 @@ def _parameter_default(
     parameter_definition: TemplateParameterDefinition,
 ) -> TemplateValue | object:
     """Return the explicit default for a parameter, if any."""
+    # TemplateValue intentionally excludes None, so None continues to mean
+    # "no default provided" for current v1 parameter types.
     default = getattr(parameter_definition, "default", None)
     return _TEMPLATE_VALUE_MISSING if default is None else cast(TemplateValue, default)
 

server/tests/test_control_templates.py

@@ -46,6 +46,23 @@ def _template_payload() -> dict[str, object]:
     }
 
 
+def _raw_control_payload(pattern: str = "raw") -> dict[str, object]:
+    return {
+        "description": "Raw control",
+        "enabled": True,
+        "execution": "server",
+        "scope": {"step_types": ["llm"], "stages": ["pre"]},
+        "condition": {
+            "selector": {"path": "input"},
+            "evaluator": {
+                "name": "regex",
+                "config": {"pattern": pattern},
+            },
+        },
+        "action": {"decision": "deny"},
+    }
+
+
 def _create_template_control(client: TestClient) -> int:
     response = client.put(
         "/api/v1/controls",
@@ -58,6 +75,18 @@ def _create_template_control(client: TestClient) -> int:
     return response.json()["control_id"]
 
 
+def _create_raw_control(client: TestClient) -> int:
+    response = client.put(
+        "/api/v1/controls",
+        json={
+            "name": f"raw-control-{uuid.uuid4()}",
+            "data": _raw_control_payload(),
+        },
+    )
+    assert response.status_code == 200, response.text
+    return response.json()["control_id"]
+
+
 def test_render_control_template_preview_returns_rendered_control(client: TestClient) -> None:
     response = client.post("/api/v1/control-templates/render", json=_template_payload())
 
@@ -84,6 +113,23 @@ def test_create_template_backed_control_persists_template_metadata(client: TestC
     assert data["condition"]["evaluator"]["config"]["pattern"] == "hello"
 
 
+def test_raw_control_can_be_replaced_with_template_backed_control(client: TestClient) -> None:
+    control_id = _create_raw_control(client)
+
+    put_response = client.put(
+        f"/api/v1/controls/{control_id}/data",
+        json={"data": _template_payload()},
+    )
+    assert put_response.status_code == 200, put_response.text
+
+    get_response = client.get(f"/api/v1/controls/{control_id}/data")
+    assert get_response.status_code == 200, get_response.text
+    data = get_response.json()["data"]
+    assert data["template"]["description"] == "Regex denial template"
+    assert data["template_values"]["pattern"] == "hello"
+    assert data["condition"]["evaluator"]["config"]["pattern"] == "hello"
+
+
 def test_template_update_preserves_enabled_value(client: TestClient) -> None:
     control_id = _create_template_control(client)
 
@@ -157,6 +203,7 @@ def test_template_backed_control_rejects_raw_put_update(client: TestClient) -> N
     )
 
     assert response.status_code == 409
+    assert response.json()["error_code"] == "CONTROL_TEMPLATE_CONFLICT"
 
 
 def test_list_controls_includes_template_backed_flag_and_filter(client: TestClient) -> None:
@@ -167,3 +214,130 @@ def test_list_controls_includes_template_backed_flag_and_filter(client: TestClie
     controls = response.json()["controls"]
     template_control = next(control for control in controls if control["id"] == control_id)
     assert template_control["template_backed"] is True
+
+
+def test_list_controls_template_backed_false_returns_only_raw_controls(client: TestClient) -> None:
+    template_control_id = _create_template_control(client)
+    raw_control_id = _create_raw_control(client)
+
+    response = client.get("/api/v1/controls", params={"template_backed": False})
+    assert response.status_code == 200, response.text
+    control_ids = {control["id"] for control in response.json()["controls"]}
+    assert raw_control_id in control_ids
+    assert template_control_id not in control_ids
+
+
+def test_render_control_template_rejects_extra_request_fields(client: TestClient) -> None:
+    payload = _template_payload()
+    payload["execution"] = "server"
+
+    response = client.post("/api/v1/control-templates/render", json=payload)
+
+    assert response.status_code == 422
+    assert response.json()["error_code"] == "VALIDATION_ERROR"
+
+
+def test_render_control_template_maps_invalid_regex_parameter(client: TestClient) -> None:
+    payload = _template_payload()
+    payload["template_values"] = {"pattern": "["}
+
+    response = client.post("/api/v1/control-templates/render", json=payload)
+
+    assert response.status_code == 422
+    body = response.json()
+    assert body["error_code"] == "TEMPLATE_PARAMETER_INVALID"
+    assert any(
+        err.get("field") == "template_values.pattern"
+        and err.get("parameter") == "pattern"
+        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"])
+    payload["template"]["definition_template"]["condition"]["evaluator"]["config"]["pattern"] = {  # type: ignore[index]
+        "$param": "pattern",
+        "extra": True,
+    }
+
+    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("code") == "invalid_param_binding" for err in body.get("errors", []))
+
+
+def test_render_control_template_rejects_non_string_param_reference(client: TestClient) -> None:
+    payload = _template_payload()
+    payload["template"] = deepcopy(payload["template"])
+    payload["template"]["definition_template"]["condition"]["evaluator"]["config"]["pattern"] = {  # type: ignore[index]
+        "$param": 123,
+    }
+
+    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("code") == "invalid_param_binding" for err in body.get("errors", []))
+
+
+def test_render_control_template_rejects_agent_scoped_evaluator(client: TestClient) -> None:
+    payload = _template_payload()
+    payload["template"] = deepcopy(payload["template"])
+    payload["template"]["definition_template"]["condition"]["evaluator"]["name"] = "agent-x:custom"  # type: ignore[index]
+
+    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("code") == "agent_scoped_evaluator_not_supported"
+        for err in body.get("errors", [])
+    )
+
+
+def test_render_control_template_rejects_legacy_flat_format(client: TestClient) -> None:
+    payload = _template_payload()
+    payload["template"] = deepcopy(payload["template"])
+    payload["template"]["definition_template"] = {  # type: ignore[index]
+        "execution": "server",
+        "scope": {"step_types": ["llm"], "stages": ["pre"]},
+        "selector": {"path": "input"},
+        "evaluator": {
+            "name": "regex",
+            "config": {"pattern": {"$param": "pattern"}},
+        },
+        "action": {"decision": "deny"},
+    }
+
+    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("code") == "legacy_condition_format_not_supported"
+        for err in body.get("errors", [])
+    )
+
+
+def test_render_control_template_rejects_invalid_parameter_name_at_api_boundary(
+    client: TestClient,
+) -> None:
+    payload = _template_payload()
+    payload["template"] = deepcopy(payload["template"])
+    payload["template"]["parameters"] = {  # type: ignore[index]
+        "bad.name": {
+            "type": "string",
+            "label": "Bad Name",
+        }
+    }
+
+    response = client.post("/api/v1/control-templates/render", json=payload)
+
+    assert response.status_code == 422
+    assert response.json()["error_code"] == "VALIDATION_ERROR"