fix(uri-params): let model-string URI beat A-leg body and extra_body

ParameterResolutionService now merges config, header, request, uri, session, and connector_forced in that rising-priority order so URI query parameters on the routed model id override duplicate top-level JSON fields and extra_body values while session and connector-forced settings still win.

Updated uri-model-parameters.md to document the full chain and reasoning_effort notes. Adjusted unit and integration tests accordingly.

Made-with: Cursor

Author: Mateusz

docs/user_guide/features/uri-model-parameters.md

@@ -18,7 +18,7 @@ This feature is particularly useful when you need to:
 - **Inline Parameter Specification**: Append parameters to model strings using URI syntax (e.g., `backend:model?temperature=0.5`)
 - **Multiple Parameters**: Support for multiple parameters in a single model string (e.g., `?temperature=0.5&reasoning_effort=high`)
 - **Hybrid Backend Support**: Apply different parameters to reasoning and execution models independently
-- **Clear Precedence**: URI parameters override config and headers but respect interactive session commands
+- **Clear Precedence**: URI parameters on the model selector override A-leg JSON body fields, `extra_body`, and config; session commands and connector-forced settings can still override URI
 - **Graceful Error Handling**: Invalid parameters are logged but don't break requests
 
 ## Configuration
@@ -28,24 +28,26 @@ This feature is particularly useful when you need to:
 The following parameters can be specified via URI syntax:
 
 - **temperature**: Controls randomness in model outputs (0.0-2.0)
-- **reasoning_effort**: Controls computational effort for reasoning models (low/medium/high)
+- **reasoning_effort**: Controls computational effort for reasoning models (`low` / `medium` / `high`; OpenAI Codex backends also support `xhigh` where the upstream API allows it)
 - **top_p**: Controls diversity via nucleus sampling (e.g., 0.9)
 - **top_k**: Controls diversity by filtering to the K most likely next tokens (e.g., 40)
 
 ### Parameter Precedence
 
 Parameters are resolved from multiple sources with the following precedence (highest to lowest):
 
-1. **Interactive Session Commands** (highest priority) - `!/temperature(0.5)`
-2. **URI Parameters** - `model?temperature=0.5`
-3. **Request Headers** - `X-Temperature: 0.5`
-4. **Configuration File** (lowest priority) - `config.yaml`
+1. **Connector-forced settings** (backend `extra` / connector policy) — hard overrides from configuration
+2. **Interactive session** — session reasoning mode and commands such as `!/temperature(0.5)` (and edit-precision promotions where applicable)
+3. **URI parameters** — query string on the routed model id, e.g. `openai-codex:gpt-5.4-mini?reasoning_effort=xhigh`
+4. **A-leg request body** — top-level OpenAI-style fields on the inbound request (for example `temperature`, `reasoning_effort`) when they were actually supplied by the client (schema defaults are not treated as overrides)
+5. **`extra_body` sampling fields** — same parameter names carried in `extra_body` (lower than top-level body for resolution)
+6. **Backend / app configuration** — defaults from `config.yaml` and backend blocks
 
 When the same parameter is specified in multiple sources, the higher priority source wins. This allows you to:
 
 - Set defaults in config files
-- Override per-request with URI parameters
-- Override dynamically with session commands
+- Let the client send common API fields, but **prefer the model string** when you encode tuning in `backend:model?...`
+- Override dynamically with session commands (or connector-forced policy when operators require it)
 
 ### Debug Logging
 
@@ -278,7 +280,7 @@ curl ... -d '{"model": "openai:gpt-4?temperature=0.8", ...}'
 
 **Solutions**:
 
-1. Check parameter precedence - session commands override URI parameters
+1. Check parameter precedence — session and connector-forced settings override URI; URI overrides duplicate fields on the A-leg request body or in `extra_body`
 2. Verify parameter name spelling (case-sensitive)
 3. Enable debug logging to see parameter resolution
 4. Check that the backend supports the parameter
@@ -290,7 +292,7 @@ curl ... -d '{"model": "openai:gpt-4?temperature=0.8", ...}'
 **Solutions**:
 
 1. Check parameter ranges (e.g., temperature: 0.0-2.0)
-2. Verify parameter format (e.g., reasoning_effort: low/medium/high)
+2. Verify parameter format (e.g., `reasoning_effort`: `low` / `medium` / `high`, and `xhigh` on supported Codex routes)
 3. Review logs for specific validation errors
 4. Consult backend documentation for supported values
 

src/core/interfaces/uri_parameter_applicator_interface.py

@@ -30,11 +30,11 @@ def apply(
         Sources and precedence (highest to lowest):
         1. Connector-forced settings (from backend config)
         2. Session overrides (from commands)
-        3. Explicit request body fields (only fields present in
+        3. URI parameters (from the model alias / query string)
+        4. Explicit A-leg request body fields (only fields present in
            ``model_fields_set`` on Pydantic requests, so schema defaults do not
            steal precedence from URI or lower sources)
-        4. URI parameters (from the model alias / query string)
-        5. Request ``extra_body`` (header-like, lower than URI)
+        5. Request ``extra_body`` (header-like)
         6. Backend / app config
 
         Type coercion rules:

src/core/services/parameter_resolution_service.py

@@ -136,8 +136,8 @@ class ParameterResolutionService:
     authoritative ordered merge:
     1. ``connector_forced_params``
     2. ``session_params``
-    3. ``request_params`` (explicit request fields)
-    4. ``uri_params``
+    3. ``uri_params`` (model string / routing selector)
+    4. ``request_params`` (explicit A-leg body fields)
     5. ``header_params`` (e.g. ``extra_body`` in the applicator)
     6. ``config_params``
 
@@ -240,8 +240,8 @@ def _resolve_single_parameter(
         Precedence order (highest to lowest):
         1. connector_forced_params
         2. session_params
-        3. request_params
-        4. uri_params
+        3. uri_params
+        4. request_params
         5. header_params
         6. config_params
 
@@ -262,8 +262,8 @@ def _resolve_single_parameter(
         sources = [
             ("config", config_params.get(param_name)),
             ("header", header_params.get(param_name)),
-            ("uri", uri_params.get(param_name)),
             ("request", request_params.get(param_name)),
+            ("uri", uri_params.get(param_name)),
             ("session", session_params.get(param_name)),
             ("connector_forced", connector_forced_params.get(param_name)),
         ]

src/core/services/uri_parameter_applicator.py

@@ -46,9 +46,9 @@ def apply(
         Sources and precedence (highest to lowest):
         1. Connector-forced settings
         2. Session overrides (from commands)
-        3. Explicit request fields
-        4. URI parameters
-        5. Request extra_body/header-like values
+        3. URI parameters (model string / selector)
+        4. Explicit A-leg request body fields
+        5. Request extra_body (header-like)
         6. Backend/app config
 
         Type coercion rules:
@@ -249,7 +249,7 @@ def _extract_header_params(
     def _extract_request_params(
         self, request: ChatRequest, backend_type: str
     ) -> dict[str, Any]:
-        """Extract explicit request fields with higher precedence than URI params.
+        """Extract explicit A-leg body fields (lower precedence than URI params).
 
         For Pydantic v2 models, only attributes listed in ``model_fields_set``
         count as user-provided. Schema defaults (e.g. ``reasoning_effort="medium"``)

tests/integration/test_uri_parameters_e2e.py

@@ -247,7 +247,7 @@ def test_session_overrides_uri(self) -> None:
         assert resolved.temperature.source == "session"
 
     def test_full_precedence_chain(self) -> None:
-        """Test complete precedence chain: session > uri > header > config."""
+        """Test complete precedence chain: session > uri > request > header > config."""
         service = ParameterResolutionService()
         resolved = service.resolve_parameters(
             config_params={"temperature": 0.1},

tests/unit/core/services/test_parameter_resolution_service.py

@@ -212,8 +212,8 @@ def test_precedence_session_overrides_all(self, service):
         assert result.temperature.value == 0.2
         assert result.temperature.source == "session"
 
-    def test_precedence_request_overrides_uri_header_and_config(self, service):
-        """Explicit request fields should override URI/header/config parameters."""
+    def test_precedence_uri_overrides_request_header_and_config(self, service):
+        """URI parameters should override A-leg request/header/config parameters."""
         result = service.resolve_parameters(
             config_params={"temperature": 0.8},
             header_params={"temperature": 0.6},
@@ -222,8 +222,8 @@ def test_precedence_request_overrides_uri_header_and_config(self, service):
         )
 
         assert result.temperature is not None
-        assert result.temperature.value == 0.3
-        assert result.temperature.source == "request"
+        assert result.temperature.value == 0.4
+        assert result.temperature.source == "uri"
 
     def test_precedence_connector_forced_overrides_everything(self, service):
         """Connector-forced parameters should have the highest precedence."""

tests/unit/core/services/test_uri_parameter_applicator.py

@@ -104,7 +104,7 @@ def test_edit_precision_promotes_request_sampling_to_session_precedence(
 
         assert result.temperature == pytest.approx(0.1)
 
-    def test_explicit_request_field_overrides_uri_defaults(self) -> None:
+    def test_uri_overrides_explicit_request_field(self) -> None:
         backend_type = "test-backend"
         config = _make_config(backend_type, extra={"temperature": 0.9})
 
@@ -122,7 +122,7 @@ def test_explicit_request_field_overrides_uri_defaults(self) -> None:
             session=None,
         )
 
-        assert result.temperature == pytest.approx(0.7)
+        assert result.temperature == pytest.approx(0.5)
 
     def test_connector_forced_overrides_uri_and_request(self) -> None:
         backend_type = "test-backend"
@@ -203,7 +203,7 @@ def test_matches_backend_service_on_simple_fixture(self) -> None:
             session,
         )
 
-        # Session > request > URI > header > config (connector_forced not used)
+        # Session > URI > request > header > config (connector_forced not used)
         assert applicator_result.temperature == 0.2