fix: add first-request override for weighted composite routing

Support [first] annotations in weighted composite selectors so one branch can be pinned for the first request in a session before normal weighted routing resumes. Persist per-session consumption state, add parser/selector/coordinator/resolver coverage, and document the behavior in routing docs and changelog.

Made-with: Cursor

Author: Mateusz

CHANGELOG.md

@@ -10,6 +10,7 @@ All notable changes to this project will be documented in this file.
 
 ### Added
 
+- **Weighted Routing `[first]` Override**: Added `[first]` annotation for weighted composite selectors (`^`) that forces the tagged backend/model for the very first request of a session, bypassing the dice roll. Subsequent requests use normal weighted routing. Accepted forms: `[first]`, `[first=1]`, `[first=yes]`, `[first=true]`. Exactly one branch may be tagged; negative forms (`[first=false]`, etc.) are rejected. Weight on the first-tagged branch does not affect the first request. Session flag (`weighted_first_request_consumed`) is persisted after first routing and ignored on retry paths. See [Routing Selectors](docs/development_guide/routing-selectors.md).
 - **Composite Model Routing**: Added ordered failover (`|`) and weighted random (`^`) selector syntax for intelligent backend failover and traffic distribution
 - **OpenCode Go Connector**: New hybrid connector for OpenCode Go with dedicated user guide and environment key support
 - **Ollama Local Connector**: Connect to locally running Ollama instances with support for both local and cloud model discovery (30-min TTL cache)

docs/development_guide/routing-selectors.md

@@ -47,6 +47,33 @@ Uses `^` with optional `[weight=N]` prefixes for weighted distribution:
 
 This distributes traffic 75% to OpenAI and 25% to Anthropic.
 
+#### First-Request Override in Weighted Routing
+
+Add a `[first]` annotation to one branch to force that backend/model for the very first request of a session. Subsequent requests use normal weighted routing based on weights.
+
+```
+openai-codex:gpt-5.3-codex?reasoning_effort=low^[first]openai-codex:gpt-5.4?reasoning_effort=xhigh
+```
+
+On the first request of a session, the `[first]`-tagged branch is selected regardless of weight. From the second request onward, weighted routing applies normally (equal 50/50 split in this example since no `[weight=N]` annotations are present).
+
+Accepted annotation forms: `[first]`, `[first=1]`, `[first=yes]`, `[first=true]`. Forms like `[first=false]`, `[first=0]`, `[first=no]` are rejected.
+
+Rules:
+- **Exactly one** branch may be tagged `[first]` per weighted selector. Multiple `[first]` tags cause a validation error.
+- The `[first]` tag only affects the first request of a session. A session-level flag (`weighted_first_request_consumed`) is set after the first request is routed, ensuring subsequent requests use weighted selection even if routing fails and retries.
+- Retry paths (failover bridge) ignore the `[first]` tag and always use weighted selection among remaining candidates.
+- The weight on the `[first]`-tagged branch does not influence the first request; it only applies from the second request onward.
+- The `[first]` annotation is only valid within weighted (`^`) selectors. Using it in failover (`|`) selectors is a validation error.
+
+Combining both annotations on the same branch:
+
+```
+[first][weight=3]openai:gpt-4^[weight=1]anthropic:claude-3-5-sonnet
+```
+
+This uses gpt-4 for the first session request, then routes 75% / 25% weighted distribution from the second request onward.
+
 ### Selector Rules
 
 1. **No mixing operators** - Composite selectors must not mix `|` and `^` in the same selector string. These are rejected during validation.
@@ -73,6 +100,9 @@ python -m src.core.cli --default-backend "openai:gpt-4o|anthropic:claude-3-5-son
 
 # Weighted routing
 python -m src.core.cli --default-backend "[weight=3]openai:gpt-4^[weight=1]anthropic:claude-3-5-sonnet"
+
+# Weighted with first-request override
+python -m src.core.cli --default-backend "[weight=3]openai:gpt-4^[first][weight=1]anthropic:claude-3-5-sonnet"
 ```
 
 ### Environment Variables

src/core/domain/composite_routing.py

@@ -107,6 +107,7 @@ class CompositeLeafSelector(DomainModel):
     raw_selector: str
     normalized_selector: str
     weight_annotation: int | None = None
+    first_annotation: bool = False
     uri_params: dict[str, JsonValue] = Field(default_factory=dict)
     backend_type: str = ""
     model_name: str = ""
@@ -128,6 +129,13 @@ def _validate_weight_annotation(cls, value: int | None) -> int | None:
             raise ValueError("weight annotation must be positive")
         return value
 
+    @field_validator("first_annotation")
+    @classmethod
+    def _validate_first_annotation(cls, value: bool) -> bool:
+        if not isinstance(value, bool):
+            raise ValueError("first_annotation must be a boolean")
+        return value
+
 
 class CompositeLeafNode(DomainModel):
     """Leaf node that can be resolved by existing single-target selector semantics."""
@@ -296,6 +304,7 @@ class CompositeRoutingInput(DomainModel):
     configured_max_hops: int | None = None
     max_branch_history: int = _DEFAULT_BRANCH_HISTORY_LIMIT
     default_backend: str = ""
+    prefer_first_weighted_branch: bool = False
 
     @field_validator("selector")
     @classmethod

src/core/domain/session.py

@@ -88,6 +88,7 @@ class SessionState(ValueObject):
     # (main model, excluding tool-result continuations and replacement-model turns).
     quality_verifier_eligible_turn_count: int = 0
     auto_append_first_prompt_applied: bool = False
+    weighted_first_request_consumed: bool = False
 
     def with_backend_config(self, backend_config: BackendConfiguration) -> SessionState:
         """Create a new session state with updated backend config."""
@@ -172,6 +173,10 @@ def with_auto_append_first_prompt_applied(self, applied: bool) -> SessionState:
         """Create a new session state with updated auto-append-first-prompt flag."""
         return self.model_copy(update={"auto_append_first_prompt_applied": applied})
 
+    def with_weighted_first_request_consumed(self, consumed: bool) -> SessionState:
+        """Create a new session state with updated weighted_first_request_consumed flag."""
+        return self.model_copy(update={"weighted_first_request_consumed": consumed})
+
     def with_multiple_updates(self, **updates: Any) -> SessionState:
         """Create a new session state with multiple field updates in a single model_copy operation.
 
@@ -341,6 +346,11 @@ def auto_append_first_prompt_applied(self) -> bool:
         """Whether the per-session first user-message append has already run."""
         return bool(getattr(self._state, "auto_append_first_prompt_applied", False))
 
+    @property
+    def weighted_first_request_consumed(self) -> bool:
+        """Whether the weighted routing [first] request has been consumed."""
+        return bool(getattr(self._state, "weighted_first_request_consumed", False))
+
     @property
     def planning_phase_turn_count(self) -> int:
         """Number of turns completed in planning phase."""

src/core/services/backend_model_resolver.py

@@ -23,6 +23,7 @@
     parse_model_with_params,
 )
 from src.core.domain.request_context import RequestContext
+from src.core.domain.session import SessionState
 from src.core.interfaces.backend_lifecycle_manager_interface import (
     IBackendLifecycleManager,
 )
@@ -142,6 +143,18 @@ async def resolve_target(
                 should_route_via_composite = True
 
             if should_route_via_composite:
+                session, prefer_first_weighted_branch = (
+                    await self._resolve_weighted_first_session_state(
+                        request=request,
+                        context=context,
+                    )
+                )
+                should_consume_weighted_first_flag = bool(
+                    session is not None
+                    and not bool(
+                        getattr(session.state, "weighted_first_request_consumed", False)
+                    )
+                )
                 composite_input = CompositeRoutingInput(
                     selector=selector_for_routing,
                     surface=routing_surface,
@@ -150,12 +163,27 @@ async def resolve_target(
                     ),
                     configured_max_hops=self._resolve_max_hops_from_config(),
                     default_backend=self._resolve_default_backend(),
+                    prefer_first_weighted_branch=prefer_first_weighted_branch,
                 )
-                return await self._composite_routing_service.resolve_target(
-                    routing_input=composite_input,
-                    request=request,
-                    context=context,
-                )
+                try:
+                    return await self._composite_routing_service.resolve_target(
+                        routing_input=composite_input,
+                        request=request,
+                        context=context,
+                    )
+                finally:
+                    if should_consume_weighted_first_flag:
+                        session_for_update = cast(Any, session)
+                        base_state = self._session_state_as_session_state(
+                            session_for_update.state
+                        )
+                        if base_state is not None:
+                            session_for_update.update_state(
+                                base_state.with_weighted_first_request_consumed(True)
+                            )
+                            await self._session_service.update_session(
+                                session_for_update
+                            )
 
         # Extract session ID and fetch session
         session_id = (
@@ -451,6 +479,50 @@ def _build_default_composite_routing_service(self) -> CompositeRoutingService:
             diagnostics_publisher=diagnostics_publisher,
         )
 
+    @staticmethod
+    def _session_state_as_session_state(state_obj: Any) -> SessionState | None:
+        if isinstance(state_obj, SessionState):
+            return state_obj
+
+        to_dict_fn = getattr(state_obj, "to_dict", None)
+        if callable(to_dict_fn):
+            raw_state = to_dict_fn()
+            if isinstance(raw_state, dict):
+                try:
+                    return cast(SessionState, SessionState.from_dict(raw_state))
+                except Exception:
+                    return None
+        return None
+
+    async def _resolve_weighted_first_session_state(
+        self,
+        *,
+        request: ChatRequest,
+        context: RequestContext | None,
+    ) -> tuple[Any | None, bool]:
+        session_id: str | None = None
+        if context is not None and isinstance(context.session_id, str):
+            candidate = context.session_id.strip()
+            if candidate:
+                session_id = candidate
+        if session_id is None and isinstance(request.extra_body, dict):
+            extra_session_id = request.extra_body.get("session_id")
+            if isinstance(extra_session_id, str):
+                candidate = extra_session_id.strip()
+                if candidate:
+                    session_id = candidate
+
+        if session_id is None:
+            return None, True
+
+        session = cast(Any, await self._session_service.get_session(session_id))
+        if session is None:
+            return None, True
+
+        return session, not bool(
+            getattr(session.state, "weighted_first_request_consumed", False)
+        )
+
     def _resolve_default_backend(self) -> str:
         app_config = cast(AppConfig, self._config)
         if hasattr(app_config, "backends"):

src/core/services/composite_routing_coordinator.py

@@ -103,7 +103,9 @@ async def execute(
                 )
             return resolved
         if isinstance(root, CompositeWeightedGroupNode):
-            selected_leaf = self._weighted_branch_selector.select(root)
+            selected_leaf = self._weighted_branch_selector.select(
+                root, prefer_first=routing_input.prefer_first_weighted_branch
+            )
             resolved = await self._resolve_leaf(
                 request=request,
                 context=context,

src/core/services/composite_selector_parser.py

@@ -25,6 +25,10 @@
 __all__ = ["CompositeSelectorParser"]
 
 _WEIGHT_PREFIX_PATTERN = re.compile(r"^\[weight=([^\]]+)\](.*)$")
+_FIRST_PREFIX_PATTERN = re.compile(r"^\[first(?:=(true|yes|1))?\](.*)$", re.IGNORECASE)
+_FIRST_NEGATIVE_PREFIX_PATTERN = re.compile(
+    r"^\[first=(false|no|0)\](.*)$", re.IGNORECASE
+)
 _INTEGER_PATTERN = re.compile(r"^[+-]?\d+$")
 
 
@@ -103,6 +107,13 @@ def parse(self, routing_input: CompositeRoutingInput) -> CompositeRoutePlan:
                 )
                 for segment in parts
             ]
+            first_count = sum(1 for leaf in leaves if leaf.leaf.first_annotation)
+            if first_count > 1:
+                self._raise_validation_error(
+                    code=CompositeValidationErrorCode.UNSUPPORTED_CONSTRUCT,
+                    selector=routing_input.selector,
+                    message="Only one branch can have a [first] annotation in a weighted group.",
+                )
             normalized = "^".join(leaf.normalized_leaf_for_plan for leaf in leaves)
             return CompositeRoutePlan(
                 source_selector=routing_input.selector,
@@ -182,25 +193,51 @@ def _parse_leaf(
             )
 
         weight_annotation: int | None = None
+        first_annotation: bool = False
         normalized_leaf_selector = raw_leaf_text
         normalized_leaf_for_plan = raw_leaf_text
 
         if is_weighted_group:
-            weight_annotation, normalized_leaf_selector = self._extract_weight_prefix(
-                raw_leaf_text,
+            remaining = raw_leaf_text
+            weight_annotation = None
+            first_annotation = False
+
+            # Extract first prefix regardless of order (could be [first] or [weight=N])
+            first_annotation, remaining = self._extract_first_prefix(
+                remaining,
                 source_selector=routing_input.selector,
             )
+            weight_annotation, remaining = self._extract_weight_prefix(
+                remaining,
+                source_selector=routing_input.selector,
+            )
+
+            # If first pass didn't find [first], try after extracting [weight]
+            if not first_annotation:
+                first_annotation, remaining = self._extract_first_prefix(
+                    remaining,
+                    source_selector=routing_input.selector,
+                )
+
+            normalized_leaf_selector = remaining
             if weight_annotation is None:
                 weight_annotation = 1
-            normalized_leaf_for_plan = (
-                f"[weight={weight_annotation}]{normalized_leaf_selector}"
-            )
+            prefix_parts = ""
+            prefix_parts += f"[weight={weight_annotation}]"
+            prefix_parts += "[first]" if first_annotation else ""
+            normalized_leaf_for_plan = f"{prefix_parts}{normalized_leaf_selector}"
         elif raw_leaf_text.startswith("[weight="):
             self._raise_validation_error(
                 code=CompositeValidationErrorCode.UNSUPPORTED_CONSTRUCT,
                 selector=routing_input.selector,
                 message="Weight annotations are only supported for weighted ('^') selectors.",
             )
+        elif "[first" in raw_leaf_text.lower() and raw_leaf_text.startswith("[first"):
+            self._raise_validation_error(
+                code=CompositeValidationErrorCode.UNSUPPORTED_CONSTRUCT,
+                selector=routing_input.selector,
+                message="First annotations are only supported for weighted ('^') selectors.",
+            )
 
         parsed_leaf = parse_model_with_params(
             normalized_leaf_selector,
@@ -242,6 +279,7 @@ def _parse_leaf(
             raw_selector=raw_leaf_text,
             normalized_selector=normalized_leaf_selector,
             weight_annotation=weight_annotation if is_weighted_group else None,
+            first_annotation=first_annotation if is_weighted_group else False,
             uri_params=parsed_leaf.uri_params,
             backend_type=parsed_leaf.backend_type,
             model_name=parsed_leaf.model_name,
@@ -296,6 +334,37 @@ def _extract_weight_prefix(
 
         return weight_value, trailing_selector.strip()
 
+    def _extract_first_prefix(
+        self,
+        leaf_text: str,
+        *,
+        source_selector: str,
+    ) -> tuple[bool, str]:
+        # Reject negative forms like [first=false], [first=0], [first=no]
+        neg_match = _FIRST_NEGATIVE_PREFIX_PATTERN.match(leaf_text)
+        if neg_match:
+            self._raise_validation_error(
+                code=CompositeValidationErrorCode.UNSUPPORTED_CONSTRUCT,
+                selector=source_selector,
+                message=f"Unsupported [first] annotation '{neg_match.group(0)}'. Use [first] without negation.",
+            )
+
+        match = _FIRST_PREFIX_PATTERN.match(leaf_text)
+        if not match:
+            return False, leaf_text
+
+        trailing_selector = match.group(2) or ""
+        if not trailing_selector or trailing_selector[0].isspace():
+            self._raise_validation_error(
+                code=CompositeValidationErrorCode.UNSUPPORTED_CONSTRUCT,
+                selector=source_selector,
+                message=(
+                    "[first] must appear immediately before a selector without whitespace."
+                ),
+            )
+
+        return True, trailing_selector.strip()
+
     @staticmethod
     def _raise_validation_error(
         *,

src/core/services/weighted_branch_selector.py

@@ -60,10 +60,30 @@ def select_index_from_weights(self, weights: Sequence[int]) -> int:
 
         return len(normalized_weights) - 1
 
-    def select(self, weighted_node: CompositeWeightedGroupNode) -> CompositeLeafNode:
+    def select(
+        self,
+        weighted_node: CompositeWeightedGroupNode,
+        *,
+        prefer_first: bool = False,
+    ) -> CompositeLeafNode:
         if not weighted_node.children:
             raise ValueError("Weighted node must contain at least one branch.")
 
+        if prefer_first:
+            first_branches = [
+                child
+                for child in weighted_node.children
+                if child.leaf_selector.first_annotation
+            ]
+            if len(first_branches) == 1:
+                return first_branches[0]
+            if len(first_branches) > 1:
+                raise ValueError(
+                    "multiple branches annotated with [first]; "
+                    "exactly one is required when prefer_first is enabled"
+                )
+            # No first_annotation found — fall through to weighted selection
+
         normalized_weights: list[int] = []
         for branch in weighted_node.children:
             weight = branch.leaf_selector.weight_annotation