coderouter-cli 2.6.0__py3-none-any.whl → 2.7.0__py3-none-any.whl

coderouter/adapters/anthropic_native.py

@@ -35,6 +35,7 @@ from collections.abc import AsyncIterator
 from typing import Any
 
 import httpx
+from pydantic import ValidationError
 
 from coderouter.adapters.base import (
     AdapterError,
@@ -68,6 +69,26 @@ _RETRYABLE_STATUSES = {404, 408, 425, 429, 500, 502, 503, 504}
 _DEFAULT_ANTHROPIC_VERSION = "2023-06-01"
 
 
+def anthropic_messages_url(base_url: str) -> str:
+    """Resolve the ``/v1/messages`` endpoint URL from a ``base_url``.
+
+    ``base_url`` may be given with or without a trailing ``/v1`` — users
+    may point it at either ``https://api.anthropic.com`` or
+    ``https://api.anthropic.com/v1`` (LM Studio and similar servers
+    commonly advertise the latter). We normalize by stripping a trailing
+    ``/v1`` so appending ``/v1/messages`` always yields a valid,
+    non-duplicated URL.
+
+    Shared by :class:`AnthropicAdapter` and the continuous-probe guard so
+    both hit the exact same endpoint (see bug H4: a mismatch made the
+    probe target ``/v1/v1/messages`` and 404 on healthy backends).
+    """
+    base = base_url.rstrip("/")
+    if base.endswith("/v1"):
+        base = base[: -len("/v1")]
+    return f"{base}/v1/messages"
+
+
 class AnthropicAdapter(BaseAdapter):
     """Native Anthropic Messages API adapter (passthrough).
 
@@ -87,15 +108,10 @@ class AnthropicAdapter(BaseAdapter):
 
         ``base_url`` may be given with or without a trailing ``/v1`` —
         we normalize by stripping it so appending ``/v1/messages``
-        always yields a valid URL.
+        always yields a valid URL. Delegates to the shared
+        :func:`anthropic_messages_url` helper.
         """
-        base = str(self.config.base_url).rstrip("/")
-        # Users may point base_url at either `https://api.anthropic.com`
-        # or `https://api.anthropic.com/v1`. We normalize to the former so
-        # we can always append /v1/messages.
-        if base.endswith("/v1"):
-            base = base[: -len("/v1")]
-        return f"{base}/v1/messages"
+        return anthropic_messages_url(str(self.config.base_url))
 
     def _headers(self, request: AnthropicRequest | None = None) -> dict[str, str]:
         """Build Anthropic-native HTTP headers, including beta-header forwarding.
@@ -161,21 +177,21 @@ class AnthropicAdapter(BaseAdapter):
         that auth works and the endpoint is reachable.
         """
         try:
-            async with httpx.AsyncClient(timeout=5.0) as client:
-                resp = await client.post(
-                    self._url(),
-                    headers=self._headers(),
-                    json={
-                        "model": self.config.model,
-                        "max_tokens": 1,
-                        "messages": [{"role": "user", "content": "ping"}],
-                    },
-                )
-                # 200 is clearly healthy. 4xx auth errors indicate the
-                # endpoint is reachable even if the key is bad — still a
-                # "the server answered" signal for healthcheck purposes.
-                # 5xx is upstream trouble.
-                return resp.status_code < 500
+            resp = await self.client().post(
+                self._url(),
+                headers=self._headers(),
+                json={
+                    "model": self.config.model,
+                    "max_tokens": 1,
+                    "messages": [{"role": "user", "content": "ping"}],
+                },
+                timeout=5.0,
+            )
+            # 200 is clearly healthy. 4xx auth errors indicate the
+            # endpoint is reachable even if the key is bad — still a
+            # "the server answered" signal for healthcheck purposes.
+            # 5xx is upstream trouble.
+            return resp.status_code < 500
         except httpx.HTTPError:
             return False
 
@@ -331,8 +347,9 @@ class AnthropicAdapter(BaseAdapter):
         timeout = self.effective_timeout(overrides)
 
         try:
-            async with httpx.AsyncClient(timeout=timeout) as client:
-                resp = await client.post(url, json=payload, headers=self._headers(request))
+            resp = await self.client().post(
+                url, json=payload, headers=self._headers(request), timeout=timeout
+            )
         except httpx.TimeoutException as exc:
             raise AdapterError(
                 f"timeout contacting {url}", provider=self.name, retryable=True
@@ -394,7 +411,22 @@ class AnthropicAdapter(BaseAdapter):
         # (future additions like thinking blocks) pass through via
         # extra="allow" on AnthropicResponse.
         data["coderouter_provider"] = self.name
-        return AnthropicResponse.model_validate(data)
+        # M6: guard the model validation. A 200 body that isn't a valid
+        # Anthropic Messages response (missing ``content``/``id``, an
+        # error envelope returned with a 200, etc.) would otherwise raise
+        # a bare pydantic ValidationError that escapes the engine's
+        # AdapterError-based retry/fallback path. Convert to a retryable
+        # AdapterError so the chain can fall through (mirrors the
+        # invalid-JSON branch above, but retryable — a malformed shape is
+        # usually transient upstream noise rather than a config fault).
+        try:
+            return AnthropicResponse.model_validate(data)
+        except ValidationError as exc:
+            raise AdapterError(
+                f"malformed response shape from upstream: {exc}",
+                provider=self.name,
+                retryable=True,
+            ) from exc
 
     async def stream_anthropic(
         self,
@@ -424,10 +456,14 @@ class AnthropicAdapter(BaseAdapter):
         logged_flag: list[bool] = [False]
 
         try:
-            async with (
-                httpx.AsyncClient(timeout=timeout) as client,
-                client.stream("POST", url, json=payload, headers=self._headers(request)) as resp,
-            ):
+            # H3: stream over the shared client (pool / keep-alive / TLS
+            # reuse). Only the ``stream(...)`` context is scoped here; the
+            # client persists and is closed via ``aclose`` on shutdown. The
+            # ``async with`` releases the response's borrowed connection even
+            # if the caller abandons this generator mid-stream — no GC leak.
+            async with self.client().stream(
+                "POST", url, json=payload, headers=self._headers(request), timeout=timeout
+            ) as resp:
                 if resp.status_code >= 400:
                     body = await resp.aread()
                     raise AdapterError(

coderouter/adapters/base.py

@@ -11,6 +11,7 @@ from abc import ABC, abstractmethod
 from collections.abc import AsyncIterator
 from typing import Any, Literal
 
+import httpx
 from pydantic import BaseModel, ConfigDict, Field
 
 from coderouter.config.schemas import ProviderConfig
@@ -164,17 +165,59 @@ class BaseAdapter(ABC):
     def __init__(self, config: ProviderConfig) -> None:
         """Bind the adapter to a :class:`ProviderConfig`.
 
-        Subclasses do not need to override this; HTTP clients are
-        constructed lazily inside :meth:`generate` / :meth:`stream` so
-        each call can honor a per-call timeout override.
+        Subclasses do not need to override this. A single shared
+        :class:`httpx.AsyncClient` is created lazily on first use (see
+        :meth:`client`) and reused across every call on this adapter so
+        the connection pool, HTTP keep-alive, and TLS session are all
+        reused. Per-call timeouts are still honored by passing
+        ``timeout=`` to ``client.post`` / ``client.stream`` — they do
+        NOT require a fresh client.
         """
         self.config = config
+        # Shared client, created lazily inside the running event loop the
+        # first time an adapter method needs it (see ``client``). Kept as
+        # ``None`` until then so constructing an adapter has no I/O cost and
+        # is safe outside an event loop (e.g. at import / config time).
+        self._client: httpx.AsyncClient | None = None
 
     @property
     def name(self) -> str:
         """Shortcut for ``self.config.name`` — used in log trails and errors."""
         return self.config.name
 
+    # ---- H3: shared HTTP client (connection-pool / keep-alive reuse) ----
+    def client(self) -> httpx.AsyncClient:
+        """Return the shared :class:`httpx.AsyncClient`, creating it lazily.
+
+        The client is created on first use so construction happens inside
+        the running event loop and carries no I/O cost at adapter-build
+        time. Subsequent calls return the same instance, which is what
+        lets httpx reuse pooled connections, keep-alive, and the TLS
+        session across requests.
+
+        No default timeout is baked in here: every call site passes an
+        explicit per-call ``timeout=`` (resolved from the active profile
+        via :meth:`effective_timeout`), so leaving the client timeout
+        unset avoids a surprising default clamping long-running calls.
+        """
+        if self._client is None:
+            self._client = httpx.AsyncClient(timeout=None)
+        return self._client
+
+    async def aclose(self) -> None:
+        """Close the shared HTTP client and drop the reference.
+
+        Idempotent: safe to call when no client was ever created, and
+        safe to call more than once. Invoked from the app lifespan
+        shutdown path so pooled connections are released cleanly rather
+        than left to garbage collection. After ``aclose`` a later call
+        re-creates the client on demand via :meth:`client`.
+        """
+        client = self._client
+        self._client = None
+        if client is not None:
+            await client.aclose()
+
     # ---- v0.6-B override resolution helpers -----------------------------
     def effective_timeout(self, overrides: ProviderCallOverrides | None) -> float:
         """Profile override wins when set; else provider default."""

coderouter/adapters/openai_compat.py

@@ -19,6 +19,7 @@ from collections.abc import AsyncIterator
 from typing import Any
 
 import httpx
+from pydantic import ValidationError
 
 from coderouter.adapters.base import (
     AdapterError,
@@ -197,9 +198,8 @@ class OpenAICompatAdapter(BaseAdapter):
         base = str(self.config.base_url).rstrip("/")
         url = f"{base}/models"
         try:
-            async with httpx.AsyncClient(timeout=5.0) as client:
-                resp = await client.get(url, headers=self._headers())
-                return resp.status_code < 500
+            resp = await self.client().get(url, headers=self._headers(), timeout=5.0)
+            return resp.status_code < 500
         except httpx.HTTPError:
             return False
 
@@ -221,8 +221,9 @@ class OpenAICompatAdapter(BaseAdapter):
         payload = self._payload(request, stream=False, overrides=overrides)
         timeout = self.effective_timeout(overrides)
         try:
-            async with httpx.AsyncClient(timeout=timeout) as client:
-                resp = await client.post(url, json=payload, headers=self._headers())
+            resp = await self.client().post(
+                url, json=payload, headers=self._headers(), timeout=timeout
+            )
         except httpx.TimeoutException as exc:
             raise AdapterError(
                 f"timeout contacting {url}", provider=self.name, retryable=True
@@ -287,7 +288,22 @@ class OpenAICompatAdapter(BaseAdapter):
 
         # Tag the response with which provider answered
         data.setdefault("object", "chat.completion")
-        return ChatResponse(coderouter_provider=self.name, **data)
+        # M6: a syntactically valid JSON body may still not be a valid
+        # Chat Completions response (e.g. an OpenAI-compat server that
+        # returns ``{"error": ...}`` with a 200, or omits ``choices``).
+        # pydantic raises ValidationError here; if left uncaught it would
+        # propagate past the engine's AdapterError-based retry/fallback
+        # logic. Convert to a retryable AdapterError so the chain can fall
+        # through to the next provider (mirrors the invalid-JSON branch,
+        # but retryable since a malformed shape is often transient).
+        try:
+            return ChatResponse(coderouter_provider=self.name, **data)
+        except ValidationError as exc:
+            raise AdapterError(
+                f"malformed response shape from upstream: {exc}",
+                provider=self.name,
+                retryable=True,
+            ) from exc
 
     async def stream(
         self,
@@ -312,6 +328,10 @@ class OpenAICompatAdapter(BaseAdapter):
         # produce dozens of duplicate log lines.
         strip_reasoning = not self.config.capabilities.reasoning_passthrough
         reasoning_logged = False
+        # M6: one-shot dedupe flag for the malformed-chunk warning. A single
+        # broken stream can emit many non-conforming chunks; we skip each one
+        # but log only on the first to avoid a log flood.
+        malformed_chunk_logged = False
 
         # v1.0-A: stateful output_filters chain for the duration of this
         # stream. Handles `<think>...</think>` / stop markers that split
@@ -325,10 +345,16 @@ class OpenAICompatAdapter(BaseAdapter):
         # seen chunk's id/model so the flush emission looks native.
         last_chunk_template: dict[str, Any] | None = None
         try:
-            async with (
-                httpx.AsyncClient(timeout=timeout) as client,
-                client.stream("POST", url, json=payload, headers=self._headers()) as resp,
-            ):
+            # H3: stream over the shared client so the connection pool /
+            # keep-alive / TLS session are reused. Only the ``stream(...)``
+            # context is entered here — the client itself outlives the
+            # stream and is closed via ``aclose`` on app shutdown. The
+            # ``async with`` guarantees the response (and its borrowed
+            # connection) is released even if the consumer abandons this
+            # generator mid-stream, so no connection leaks on GC.
+            async with self.client().stream(
+                "POST", url, json=payload, headers=self._headers(), timeout=timeout
+            ) as resp:
                 if resp.status_code >= 400:
                     body = await resp.aread()
                     raise AdapterError(
@@ -375,7 +401,23 @@ class OpenAICompatAdapter(BaseAdapter):
                             if isinstance(content, str) and content:
                                 delta["content"] = filter_chain.feed(content)
                         last_chunk_template = payload_obj
-                    yield StreamChunk(**payload_obj)
+                    # M6: a chunk may be valid JSON yet not a valid
+                    # StreamChunk (e.g. a mid-stream ``{"error": ...}``
+                    # frame, or a chunk missing required fields). Rather
+                    # than let the ValidationError abort the whole stream
+                    # (bypassing the engine's AdapterError handling), skip
+                    # the bad chunk and keep consuming. Warn once per stream.
+                    try:
+                        chunk = StreamChunk(**payload_obj)
+                    except ValidationError as exc:
+                        if not malformed_chunk_logged:
+                            logger.warning(
+                                "malformed-stream-chunk",
+                                extra={"provider": self.name, "error": str(exc)},
+                            )
+                            malformed_chunk_logged = True
+                        continue
+                    yield chunk
 
             # v1.0-A: flush the chain at end-of-stream. If filters held
             # back a partial-tag suffix that turned out NOT to be a tag,

coderouter/config/schemas.py

@@ -706,6 +706,63 @@ class FallbackChain(BaseModel):
         ),
     )
 
+    @model_validator(mode="after")
+    def _check_context_budget_thresholds_ordered(self) -> FallbackChain:
+        """v2.0-F (mE): cross-field sanity of the context-budget ratios.
+
+        The three ratios describe a strict staircase: a warning fires
+        first, then trimming kicks in at a higher usage, and trimming
+        reclaims space down to a target below the trim point. If they are
+        mis-ordered the guard is either a dead knob (warn above trim never
+        fires) or an infinite trim loop (target >= trim never converges).
+        Same fast-fail philosophy as ``_check_default_profile_exists`` —
+        surface the mistake at load with a concrete pointer to the fix
+        rather than at the first request that trips the guard.
+
+        Required invariants:
+          * ``context_budget_warn_threshold`` <= ``context_budget_trim_threshold``
+          * ``context_budget_trim_target``    <  ``context_budget_trim_threshold``
+        """
+        if self.context_budget_warn_threshold > self.context_budget_trim_threshold:
+            raise ValueError(
+                f"profile {self.name!r}: context_budget_warn_threshold "
+                f"({self.context_budget_warn_threshold}) must be <= "
+                f"context_budget_trim_threshold "
+                f"({self.context_budget_trim_threshold}) — the warning has to "
+                f"fire at or before trimming, otherwise it can never fire. "
+                f"Lower warn_threshold or raise trim_threshold."
+            )
+        if self.context_budget_trim_target >= self.context_budget_trim_threshold:
+            raise ValueError(
+                f"profile {self.name!r}: context_budget_trim_target "
+                f"({self.context_budget_trim_target}) must be < "
+                f"context_budget_trim_threshold "
+                f"({self.context_budget_trim_threshold}) — trimming must "
+                f"reclaim space *below* the trigger point, otherwise trim "
+                f"never converges. Lower trim_target below trim_threshold."
+            )
+        return self
+
+    @model_validator(mode="after")
+    def _check_recovery_probe_interval_ordered(self) -> FallbackChain:
+        """v2.0-J (mE): the recovery-probe backoff floor must not exceed its cap.
+
+        ``recovery_probe_initial_s`` is the first probe interval and each
+        failed probe doubles it up to ``recovery_probe_max_s``. When the
+        initial interval already exceeds the max, the exponential-backoff
+        ceiling is below its own floor — a nonsensical configuration that
+        the backoff loop would silently clamp. Surface it at load instead.
+        """
+        if self.recovery_probe_initial_s > self.recovery_probe_max_s:
+            raise ValueError(
+                f"profile {self.name!r}: recovery_probe_initial_s "
+                f"({self.recovery_probe_initial_s}) must be <= "
+                f"recovery_probe_max_s ({self.recovery_probe_max_s}) — the "
+                f"initial probe interval cannot exceed the backoff ceiling. "
+                f"Lower recovery_probe_initial_s or raise recovery_probe_max_s."
+            )
+        return self
+
 
 # ---------------------------------------------------------------------------
 # v1.6-A: auto_router — declarative request-body classifier
@@ -720,6 +777,14 @@ class RuleMatcher(BaseModel):
     adding a new optional field — the single-field invariant enforces
     discriminated-union semantics without pydantic's tagged-union syntax.
 
+    Boolean matchers (``has_image`` / ``has_tools``) only carry meaning at
+    ``True``: the runtime evaluator matches with ``is True`` (see
+    ``coderouter.routing.auto_router._match_rule``), so a ``False`` value
+    would construct without error yet never match anything — a dead rule
+    that silently shadows nothing and confuses operators. ``_exactly_one``
+    therefore rejects ``False`` for these fields at load (``None`` remains
+    the "unset" sentinel).
+
     Variants (v1.6-A):
 
     - ``has_image: True`` — any ``image_url`` / ``image`` /
@@ -822,8 +887,29 @@ class RuleMatcher(BaseModel):
         "cjk_ratio_min",
     )
 
+    # Boolean matcher fields carry meaning only at ``True`` — the runtime
+    # evaluator uses ``is True`` — so a ``False`` value is a dead rule that
+    # never matches. ``_exactly_one`` rejects it explicitly (see below).
+    _BOOL_MATCHER_FIELDS: tuple[str, ...] = ("has_image", "has_tools")
+
     @model_validator(mode="after")
     def _exactly_one(self) -> Self:
+        # Reject the dead-rule shape first so the error names the specific
+        # field the operator got wrong, rather than the generic
+        # "exactly one" message (``False`` counts as "set" below).
+        false_bools = [
+            name
+            for name in self._BOOL_MATCHER_FIELDS
+            if getattr(self, name) is False
+        ]
+        if false_bools:
+            raise ValueError(
+                f"RuleMatcher boolean matcher(s) set to False: {false_bools}. "
+                f"These matchers are evaluated with ``is True``, so a False "
+                f"value is a dead rule that never matches (it would silently "
+                f"shadow nothing). Use True to match, or omit the field "
+                f"(leave it None) to not use this matcher."
+            )
         set_fields = [
             name for name in self._MATCHER_FIELDS if getattr(self, name) is not None
         ]
@@ -1391,6 +1477,74 @@ class CodeRouterConfig(BaseModel):
             )
         return self
 
+    @model_validator(mode="after")
+    def _check_names_unique(self) -> CodeRouterConfig:
+        """mE: provider and profile names must each be unique.
+
+        ``provider_by_name`` / ``profile_by_name`` return the *first*
+        match, so a duplicate name silently shadows every later entry with
+        the same key — the operator's second ``local:`` block is loaded,
+        validated, and then never reachable. Reject duplicates at load with
+        the offending names, matching the fast-fail philosophy of the other
+        ``_check_*`` validators.
+        """
+        seen_p: set[str] = set()
+        dup_p: list[str] = []
+        for p in self.providers:
+            if p.name in seen_p and p.name not in dup_p:
+                dup_p.append(p.name)
+            seen_p.add(p.name)
+        if dup_p:
+            raise ValueError(
+                f"duplicate provider name(s): {sorted(dup_p)}. Provider names "
+                f"must be unique — a duplicate silently shadows the later "
+                f"entry (provider_by_name returns the first match). Rename or "
+                f"remove the duplicate(s)."
+            )
+
+        seen_f: set[str] = set()
+        dup_f: list[str] = []
+        for prof in self.profiles:
+            if prof.name in seen_f and prof.name not in dup_f:
+                dup_f.append(prof.name)
+            seen_f.add(prof.name)
+        if dup_f:
+            raise ValueError(
+                f"duplicate profile name(s): {sorted(dup_f)}. Profile names "
+                f"must be unique — a duplicate silently shadows the later "
+                f"entry (profile_by_name returns the first match). Rename or "
+                f"remove the duplicate(s)."
+            )
+        return self
+
+    @model_validator(mode="after")
+    def _check_profile_providers_exist(self) -> CodeRouterConfig:
+        """mE: every provider named in a profile chain must be declared.
+
+        Previously a typo in ``profiles[].providers`` was tolerated at load
+        and only surfaced at runtime as a ``skip-unknown-provider`` warning;
+        if *every* entry in a chain was typo'd the profile silently had no
+        usable providers and only failed once fully drained. Rejecting at
+        load — same philosophy as ``_check_default_profile_exists`` and
+        ``_check_mode_alias_targets_exist`` — turns a silent-until-drained
+        misconfig into a startup error naming the profile and the bad
+        provider(s).
+        """
+        names = {p.name for p in self.providers}
+        errors: list[str] = []
+        for prof in self.profiles:
+            missing = [name for name in prof.providers if name not in names]
+            if missing:
+                errors.append(f"{prof.name!r} -> {missing}")
+        if errors:
+            raise ValueError(
+                f"profile(s) reference undeclared provider(s): "
+                f"{'; '.join(errors)}. known providers={sorted(names)}. "
+                f"Fix the typo in profiles[].providers or add the missing "
+                f"provider(s)."
+            )
+        return self
+
     def provider_by_name(self, name: str) -> ProviderConfig:
         """Look up a provider config by name. Raises KeyError if not found."""
         for p in self.providers:

coderouter/guards/context_budget.py

@@ -339,33 +339,128 @@ def _compute_preserve_set(
     return preserved
 
 
+def _group_removable_units(
+    messages: list[Any],
+    removable: list[int],
+) -> list[list[int]]:
+    """Group removable message indices into atomic tool-pair units.
+
+    ``removable`` is the sorted list of indices eligible for removal
+    (i.e. not in the preserve set). A tool_use assistant message and the
+    user message carrying its matching tool_result must be removed
+    together so we never leave an orphaned tool_use or tool_result in the
+    trimmed history (Anthropic rejects both with a 400). Because the
+    preserve-set computation already keeps pairs atomic, both halves of a
+    pair are always either both preserved or both removable — here we just
+    coalesce the removable halves into a single unit so the incremental
+    loop drops them in one step.
+
+    Returns a list of units (each a sorted list of indices), ordered by
+    the position of the unit's earliest message so the caller can peel
+    them off the front oldest-first.
+    """
+    removable_set = set(removable)
+
+    # Map every tool_use_id to the indices of the message(s) that emit the
+    # tool_use and the message that carries the matching tool_result.
+    partner: dict[int, set[int]] = {idx: set() for idx in removable}
+    use_index: dict[str, int] = {}
+    result_index: dict[str, int] = {}
+    for idx in removable:
+        for tid in _extract_tool_use_ids(messages[idx]):
+            use_index[tid] = idx
+        for tid in _extract_tool_result_ids(messages[idx]):
+            result_index[tid] = idx
+    for tid, use_idx in use_index.items():
+        res_idx = result_index.get(tid)
+        if res_idx is not None and res_idx in removable_set:
+            partner[use_idx].add(res_idx)
+            partner[res_idx].add(use_idx)
+
+    # Union-find style grouping over the partner graph.
+    seen: set[int] = set()
+    units: list[list[int]] = []
+    for idx in removable:
+        if idx in seen:
+            continue
+        stack = [idx]
+        group: set[int] = set()
+        while stack:
+            cur = stack.pop()
+            if cur in group:
+                continue
+            group.add(cur)
+            seen.add(cur)
+            stack.extend(p for p in partner[cur] if p not in group)
+        units.append(sorted(group))
+
+    units.sort(key=lambda unit: unit[0])
+    return units
+
+
+def _normalize_head(messages: list[Any]) -> list[Any]:
+    """Drop leading messages until the first is a clean ``user`` message.
+
+    Anthropic requires the first message to be a ``user`` message, and a
+    leading user message must not open with a dangling ``tool_result``
+    (its ``tool_use`` was trimmed away). We therefore drop from the front
+    any assistant message and any user message that contains a
+    tool_result, stopping at the first ``user`` message with no
+    tool_result block.
+    """
+    start = 0
+    n = len(messages)
+    while start < n:
+        msg = messages[start]
+        role = msg.role if hasattr(msg, "role") else (
+            msg.get("role") if isinstance(msg, dict) else None
+        )
+        if role == "user" and not _has_tool_result(msg):
+            break
+        start += 1
+    return messages[start:]
+
+
 def _do_trim(
     messages: list[Any],
     system: Any,
     target_tokens: int,
     preserve_last_n: int,
 ) -> list[Any]:
-    """Core trim loop. Reduces preserve_last_n if needed (floor: 2)."""
-    current_preserve = preserve_last_n
-
-    while current_preserve >= 2:
-        preserved_indices = _compute_preserve_set(messages, current_preserve)
-        # Keep only preserved messages (maintain order)
-        trimmed = [messages[i] for i in sorted(preserved_indices)]
-
-        estimated = estimate_tokens_from_anthropic_request(
-            system=system,
-            messages=trimmed,
-        )
+    """Incrementally drop oldest messages until under ``target_tokens``.
+
+    Unlike the previous implementation (which deleted every non-preserved
+    message in one shot the moment the threshold was crossed), this peels
+    messages off the front one atomic unit at a time and re-estimates
+    after each removal, stopping as soon as the estimate is at or below
+    the target. The preserve set (last N messages + their tool pairs) is a
+    hard floor that is never removed. After trimming, the head is
+    normalized so the first surviving message is a ``user`` message
+    without a leading ``tool_result`` (avoids upstream 400s). Bug H5.
+    """
+    if not messages:
+        return messages
+
+    already = estimate_tokens_from_anthropic_request(system=system, messages=messages)
+    if already <= target_tokens:
+        # Nothing to do — return the input unchanged.
+        return messages
+
+    preserved_indices = _compute_preserve_set(messages, preserve_last_n)
+    removable = [i for i in range(len(messages)) if i not in preserved_indices]
+    units = _group_removable_units(messages, removable)
+
+    # Indices we have decided to drop; peel atomic units from the front.
+    dropped: set[int] = set()
+    for unit in units:
+        kept = [messages[i] for i in range(len(messages)) if i not in dropped]
+        estimated = estimate_tokens_from_anthropic_request(system=system, messages=kept)
         if estimated <= target_tokens:
-            return trimmed
-
-        # Still over target — reduce preserve count and retry
-        current_preserve -= 1
+            break
+        dropped.update(unit)
 
-    # Floor reached — return with minimum preservation (last 2)
-    preserved_indices = _compute_preserve_set(messages, 2)
-    return [messages[i] for i in sorted(preserved_indices)]
+    trimmed = [messages[i] for i in range(len(messages)) if i not in dropped]
+    return _normalize_head(trimmed)
 
 
 __all__ = [