feat(ui, server): Intuitive JSON editing for Controls

.github/workflows/ci.yml

@@ -143,6 +143,10 @@ jobs:
           # Use production build for faster startup
           NODE_ENV: production
 
+      - name: Run component tests
+        working-directory: ./ui
+        run: pnpm run test:ct
+
       - name: Upload Playwright report
         uses: actions/upload-artifact@v4
         if: failure()

models/src/agent_control_models/controls.py

@@ -74,6 +74,7 @@ class ControlScope(BaseModel):
             "Step types this control applies to (omit to apply to all types). "
             "Built-in types are 'tool' and 'llm'."
         ),
+        examples=[["llm"], ["tool"], ["llm", "tool"]],
     )
     step_names: list[str] | None = Field(
         default=None,
@@ -172,6 +173,7 @@ class EvaluatorSpec(BaseModel):
 
     name: str = Field(
         ...,
+        min_length=1,
         description="Evaluator name or agent-scoped reference (agent:evaluator)",
         examples=["regex", "list", "my-agent:pii-detector"],
     )
@@ -184,6 +186,17 @@ class EvaluatorSpec(BaseModel):
         ],
     )
 
+    @field_validator("name", mode="before")
+    @classmethod
+    def validate_name(cls, value: str) -> str:
+        if not isinstance(value, str):
+            return value
+
+        normalized = value.strip()
+        if not normalized:
+            raise ValueError("Evaluator name cannot be empty or whitespace-only.")
+        return normalized
+
     @model_validator(mode="after")
     def validate_evaluator_config(self) -> Self:
         """Validate config against evaluator's schema if evaluator is registered.

models/src/agent_control_models/server.py

@@ -293,6 +293,16 @@ class GetControlDataResponse(BaseModel):
     data: ControlDefinition = Field(description="Control data payload")
 
 
+class GetControlSchemaResponse(BaseModel):
+    model_config = {"populate_by_name": True}
+
+    schema_: dict[str, Any] = Field(
+        alias="schema",
+        serialization_alias="schema",
+        description="JSON Schema for a full ControlDefinition payload",
+    )
+
+
 class SetControlDataRequest(BaseModel):
     """Request to update control configuration data."""
     data: ControlDefinition = Field(

sdks/typescript/overlays/method-names.overlay.yaml

@@ -110,6 +110,11 @@ actions:
       x-speakeasy-group: controls
       x-speakeasy-name-override: create
 
+  - target: $["paths"]["/api/v1/controls/schema"]["get"]
+    update:
+      x-speakeasy-group: controls
+      x-speakeasy-name-override: getSchema
+
   - target: $["paths"]["/api/v1/controls/validate"]["post"]
     update:
       x-speakeasy-group: controls

sdks/typescript/src/generated/funcs/controls-get-schema.ts

@@ -0,0 +1,142 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { AgentControlSDKCore } from "../core.js";
+import * as M from "../lib/matchers.js";
+import { compactMap } from "../lib/primitives.js";
+import { RequestOptions } from "../lib/sdks.js";
+import { extractSecurity, resolveGlobalSecurity } from "../lib/security.js";
+import { pathToFunc } from "../lib/url.js";
+import { AgentControlSDKError } from "../models/errors/agent-control-sdk-error.js";
+import {
+  ConnectionError,
+  InvalidRequestError,
+  RequestAbortedError,
+  RequestTimeoutError,
+  UnexpectedClientError,
+} from "../models/errors/http-client-errors.js";
+import { ResponseValidationError } from "../models/errors/response-validation-error.js";
+import { SDKValidationError } from "../models/errors/sdk-validation-error.js";
+import * as models from "../models/index.js";
+import { APICall, APIPromise } from "../types/async.js";
+import { Result } from "../types/fp.js";
+
+/**
+ * Get control definition JSON schema
+ *
+ * @remarks
+ * Return the canonical JSON schema for ControlDefinition.
+ */
+export function controlsGetSchema(
+  client: AgentControlSDKCore,
+  options?: RequestOptions,
+): APIPromise<
+  Result<
+    models.GetControlSchemaResponse,
+    | AgentControlSDKError
+    | ResponseValidationError
+    | ConnectionError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | InvalidRequestError
+    | UnexpectedClientError
+    | SDKValidationError
+  >
+> {
+  return new APIPromise($do(
+    client,
+    options,
+  ));
+}
+
+async function $do(
+  client: AgentControlSDKCore,
+  options?: RequestOptions,
+): Promise<
+  [
+    Result<
+      models.GetControlSchemaResponse,
+      | AgentControlSDKError
+      | ResponseValidationError
+      | ConnectionError
+      | RequestAbortedError
+      | RequestTimeoutError
+      | InvalidRequestError
+      | UnexpectedClientError
+      | SDKValidationError
+    >,
+    APICall,
+  ]
+> {
+  const path = pathToFunc("/api/v1/controls/schema")();
+
+  const headers = new Headers(compactMap({
+    Accept: "application/json",
+  }));
+
+  const secConfig = await extractSecurity(client._options.apiKeyHeader);
+  const securityInput = secConfig == null ? {} : { apiKeyHeader: secConfig };
+  const requestSecurity = resolveGlobalSecurity(securityInput);
+
+  const context = {
+    options: client._options,
+    baseURL: options?.serverURL ?? client._baseURL ?? "",
+    operationID: "get_control_schema_api_v1_controls_schema_get",
+    oAuth2Scopes: null,
+
+    resolvedSecurity: requestSecurity,
+
+    securitySource: client._options.apiKeyHeader,
+    retryConfig: options?.retries
+      || client._options.retryConfig
+      || { strategy: "none" },
+    retryCodes: options?.retryCodes || ["429", "500", "502", "503", "504"],
+  };
+
+  const requestRes = client._createRequest(context, {
+    security: requestSecurity,
+    method: "GET",
+    baseURL: options?.serverURL,
+    path: path,
+    headers: headers,
+    userAgent: client._options.userAgent,
+    timeoutMs: options?.timeoutMs || client._options.timeoutMs || -1,
+  }, options);
+  if (!requestRes.ok) {
+    return [requestRes, { status: "invalid" }];
+  }
+  const req = requestRes.value;
+
+  const doResult = await client._do(req, {
+    context,
+    errorCodes: ["4XX", "5XX"],
+    retryConfig: context.retryConfig,
+    retryCodes: context.retryCodes,
+  });
+  if (!doResult.ok) {
+    return [doResult, { status: "request-error", request: req }];
+  }
+  const response = doResult.value;
+
+  const [result] = await M.match<
+    models.GetControlSchemaResponse,
+    | AgentControlSDKError
+    | ResponseValidationError
+    | ConnectionError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | InvalidRequestError
+    | UnexpectedClientError
+    | SDKValidationError
+  >(
+    M.json(200, models.GetControlSchemaResponse$inboundSchema),
+    M.fail("4XX"),
+    M.fail("5XX"),
+  )(response, req);
+  if (!result.ok) {
+    return [result, { status: "complete", request: req, response }];
+  }
+
+  return [result, { status: "complete", request: req, response }];
+}

sdks/typescript/src/generated/models/get-control-schema-response.ts

@@ -0,0 +1,33 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod/v4-mini";
+import { safeParse } from "../lib/schemas.js";
+import { Result as SafeParseResult } from "../types/fp.js";
+import { SDKValidationError } from "./errors/sdk-validation-error.js";
+
+export type GetControlSchemaResponse = {
+  /**
+   * JSON Schema for a full ControlDefinition payload
+   */
+  schema: { [k: string]: any };
+};
+
+/** @internal */
+export const GetControlSchemaResponse$inboundSchema: z.ZodMiniType<
+  GetControlSchemaResponse,
+  unknown
+> = z.object({
+  schema: z.record(z.string(), z.any()),
+});
+
+export function getControlSchemaResponseFromJSON(
+  jsonString: string,
+): SafeParseResult<GetControlSchemaResponse, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => GetControlSchemaResponse$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'GetControlSchemaResponse' from JSON`,
+  );
+}

sdks/typescript/src/generated/models/index.ts

@@ -45,6 +45,7 @@ export * from "./get-agent-policies-response.js";
 export * from "./get-agent-response.js";
 export * from "./get-control-data-response.js";
 export * from "./get-control-response.js";
+export * from "./get-control-schema-response.js";
 export * from "./get-policy-controls-response.js";
 export * from "./get-policy-response.js";
 export * from "./health-response.js";

sdks/typescript/src/generated/sdk/controls.ts

@@ -5,6 +5,7 @@
 import { controlsCreate } from "../funcs/controls-create.js";
 import { controlsDelete } from "../funcs/controls-delete.js";
 import { controlsGetData } from "../funcs/controls-get-data.js";
+import { controlsGetSchema } from "../funcs/controls-get-schema.js";
 import { controlsGet } from "../funcs/controls-get.js";
 import { controlsList } from "../funcs/controls-list.js";
 import { controlsUpdateData } from "../funcs/controls-update-data.js";
@@ -83,6 +84,21 @@ export class Controls extends ClientSDK {
     ));
   }
 
+  /**
+   * Get control definition JSON schema
+   *
+   * @remarks
+   * Return the canonical JSON schema for ControlDefinition.
+   */
+  async getSchema(
+    options?: RequestOptions,
+  ): Promise<models.GetControlSchemaResponse> {
+    return unwrapAsync(controlsGetSchema(
+      this,
+      options,
+    ));
+  }
+
   /**
    * Validate control configuration
    *

server/Makefile

@@ -71,5 +71,8 @@ start-dependencies:
 test:
 	$(TEST_DB_ENV) uv run --package agent-control-server pytest --cov=src --cov-report=xml:../coverage-server.xml -q
 
-run: start-dependencies migrate
+run: start-dependencies migrate run-server
+
+run-server:
 	uv run --package agent-control-server uvicorn agent_control_server.main:app --reload --host $(AGENT_CONTROL_HOST) --port $(AGENT_CONTROL_PORT)
+

server/src/agent_control_server/endpoints/controls.py

@@ -11,6 +11,7 @@
     DeleteControlResponse,
     GetControlDataResponse,
     GetControlResponse,
+    GetControlSchemaResponse,
     ListControlsResponse,
     PaginationInfo,
     PatchControlRequest,
@@ -99,7 +100,11 @@ def _serialize_control_definition(control_def: ControlDefinition) -> dict[str, o
 async def _validate_control_definition(
     control_def: ControlDefinition, db: AsyncSession
 ) -> None:
-    """Validate evaluator config for a control definition."""
+    """Validate evaluator config for definitions referencing known global evaluators.
+
+    Agent-scoped evaluators must exist on the referenced agent. Builtin and external
+    names that are not loaded in this process are accepted without config checks.
+    """
     available_evaluators = list_evaluators()
     agent_data_by_name: dict[str, AgentData] = {}
     for field_prefix, leaf in _iter_condition_leaves(control_def.condition):
@@ -211,6 +216,9 @@ async def _validate_control_definition(
 
         evaluator_cls = available_evaluators.get(parsed.name)
         if evaluator_cls is None:
+            # Global (builtin / external) evaluators may be absent from this runtime
+            # (optional packages, forward compatibility). Store the definition without
+            # config validation; evaluation will fail later if the evaluator is missing.
             continue
 
         try:
@@ -325,6 +333,19 @@ async def create_control(
     return CreateControlResponse(control_id=control.id)
 
 
+@router.get(
+    "/schema",
+    response_model=GetControlSchemaResponse,
+    summary="Get control definition JSON schema",
+    response_description="JSON schema for ControlDefinition",
+)
+async def get_control_schema() -> GetControlSchemaResponse:
+    """Return the canonical JSON schema for ControlDefinition."""
+    return GetControlSchemaResponse(
+        schema=ControlDefinition.model_json_schema(by_alias=True)
+    )
+
+
 @router.get(
     "/{control_id}",
     response_model=GetControlResponse,

server/tests/test_controls.py

@@ -2,11 +2,10 @@
 from copy import deepcopy
 from typing import Any
 
+from agent_control_server.models import Control
 from fastapi.testclient import TestClient
 from sqlalchemy.orm import Session
 
-from agent_control_server.models import Control
-
 from .conftest import engine
 
 
@@ -106,6 +105,20 @@ def test_get_control_data_initially_unconfigured(client: TestClient) -> None:
     assert "invalid data" in response_data.get("detail", "").lower()
 
 
+def test_get_control_schema_returns_control_definition_schema(client: TestClient) -> None:
+    resp = client.get("/api/v1/controls/schema")
+
+    assert resp.status_code == 200, resp.text
+    schema = resp.json()["schema"]
+    properties = schema["properties"]
+
+    assert schema["type"] == "object"
+    assert {"execution", "condition", "action"}.issubset(properties)
+    assert set(schema["required"]) >= {"execution", "condition", "action"}
+    assert "condition" in properties
+    assert "$defs" in schema
+
+
 VALID_CONTROL_DATA = {
     "description": "Test Control",
     "enabled": True,