polyrob 0.5.0__py3-none-any.whl

modules/llm/profiles.py

@@ -0,0 +1,178 @@
+"""Declarative provider profiles (roadmap P8, Reference §28).
+
+A ``ProviderProfile`` *describes* a provider — identity, auth, base URL, default
+model, capability flags — and owns no client construction, credential rotation, or
+streaming. Today POLYROB's ``modules/llm/*_client.py`` files conflate profile +
+transport + adapter; this layer extracts the declarative half so it has a single
+home. It is purely additive: nothing is rewired to consume it yet (that migration
+is the rest of P8), so behavior is unchanged.
+
+The default model deliberately reads from ``llm_client_registry.DEFAULT_MODELS`` so
+the default-model *policy* stays single-sourced.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, List, Optional
+
+from modules.llm.llm_client_registry import get_default_model
+
+
+@dataclass(frozen=True)
+class ProviderProfile:
+    name: str
+    display_name: str
+    env_key: str                      # API-key environment variable
+    auth_type: str = "api_key"        # api_key | oauth | aws
+    base_url: Optional[str] = None    # None => provider SDK default
+    supports_native_tools: bool = True
+    supports_vision: bool = True
+    signup_url: Optional[str] = None
+    initializable: bool = True        # False = key alone can't bootstrap a client
+                                      # (deepseek: direct client disabled → use OpenRouter)
+
+    @property
+    def default_model(self) -> str:
+        """The default model for this provider (single-sourced from the registry)."""
+        return get_default_model(self.name)
+
+
+# NOTE: insertion order IS the canonical preference order for "first provider with
+# a key" (see ``providers_with_keys`` / ``core.runtime_config``). OpenRouter is FIRST
+# (2026-06-24): it is the preferred default client whenever its key is present —
+# explicit ``-p`` and operator pins (DEFAULT_PROVIDER/CHAT_PROVIDER) still win.
+PROFILES: Dict[str, ProviderProfile] = {
+    "openrouter": ProviderProfile(
+        name="openrouter", display_name="OpenRouter", env_key="OPENROUTER_API_KEY",
+        base_url="https://openrouter.ai/api/v1", supports_native_tools=True,
+        supports_vision=True, signup_url="https://openrouter.ai/",
+    ),
+    "anthropic": ProviderProfile(
+        name="anthropic", display_name="Anthropic", env_key="ANTHROPIC_API_KEY",
+        base_url="https://api.anthropic.com", supports_native_tools=True,
+        supports_vision=True, signup_url="https://console.anthropic.com/",
+    ),
+    "openai": ProviderProfile(
+        name="openai", display_name="OpenAI", env_key="OPENAI_API_KEY",
+        supports_native_tools=True, supports_vision=True,
+        signup_url="https://platform.openai.com/",
+    ),
+    "gemini": ProviderProfile(
+        name="gemini", display_name="Google Gemini", env_key="GEMINI_API_KEY",
+        supports_native_tools=True, supports_vision=True,
+        signup_url="https://aistudio.google.com/",
+    ),
+    "nvidia": ProviderProfile(
+        name="nvidia", display_name="NVIDIA NIM", env_key="NVIDIA_API_KEY",
+        base_url="https://integrate.api.nvidia.com/v1", supports_native_tools=True,
+        supports_vision=False, signup_url="https://build.nvidia.com/",
+    ),
+    "deepseek": ProviderProfile(
+        name="deepseek", display_name="DeepSeek", env_key="DEEPSEEK_API_KEY",
+        base_url="https://api.deepseek.com/v1", supports_native_tools=False,
+        supports_vision=False, signup_url="https://platform.deepseek.com/",
+        # Direct client disabled (tool-calling broken) — reach DeepSeek via OpenRouter
+        # (OPENROUTER_API_KEY + model deepseek/deepseek-chat). A DEEPSEEK_API_KEY alone
+        # cannot bootstrap the agent, so it must NOT count toward "has a usable key".
+        initializable=False,
+    ),
+}
+
+
+def providers_with_keys(env=None) -> List[str]:
+    """Return provider names whose API key is present in *env*, in PROFILES order.
+
+    This is the single source of truth for "which LLM providers have a key" — it
+    replaces the divergent per-call-site key lists across the CLI (config_store,
+    chat.py, doctor.py, model.py, banner.py). The returned order IS the canonical
+    preference order for "first provider with a key".
+
+    *env* defaults to ``os.environ``; pass a mapping for testability. A blank value
+    counts as absent.
+    """
+    import os
+    env = os.environ if env is None else env
+    return [p.name for p in PROFILES.values() if env.get(p.env_key)]
+
+
+def initializable_providers_with_keys(env=None) -> List[str]:
+    """``providers_with_keys`` restricted to providers a key ALONE can bootstrap.
+
+    This is the SSOT for "does the user have a *usable* provider key" — the gating
+    oracle that ``should_warn_no_key`` / the runtime resolver / the env-backfill and
+    ``LLMManager._initialize``'s ``clients_to_try`` all derive from, so they can never
+    disagree. Excludes deepseek (direct client disabled — route via OpenRouter). The
+    raw ``providers_with_keys`` stays the DISPLAY oracle (doctor/webview show a key is
+    present even when it can't bootstrap directly).
+    """
+    import os
+    env = os.environ if env is None else env
+    return [p.name for p in PROFILES.values() if env.get(p.env_key) and p.initializable]
+
+
+# Placeholder values that are "present" but not a real key (mirrors
+# core.config.BotConfig.validate_api_keys, generalized across providers).
+_PLACEHOLDER_KEYS = {
+    "your-openai-key", "your-anthropic-key", "your-api-key", "your-alchemy-key",
+    "your-gemini-key", "your-openrouter-key", "your-key", "changeme", "none", "null",
+}
+# Real provider API keys are comfortably longer than this; BotConfig blanks shorter
+# ones for openai/anthropic. Every provider's real key (gemini ~39 is the shortest)
+# clears 20, so the bar is safe to apply across providers.
+_MIN_KEY_LEN = 20
+
+
+def looks_like_real_key(value) -> bool:
+    """True when *value* is a plausibly-real API key (not blank / placeholder / stub).
+
+    Mirrors ``BotConfig.validate_api_keys`` so the GATING oracles agree with what the
+    LLM manager will actually accept — a malformed key must NOT pass a guard only to be
+    blanked by BotConfig and crash the manager with a misleading 'No API key found'.
+    """
+    if not value:
+        return False
+    v = str(value).strip()
+    if v.lower() in _PLACEHOLDER_KEYS:
+        return False
+    return len(v) >= _MIN_KEY_LEN
+
+
+def usable_providers_with_keys(env=None) -> List[str]:
+    """Initializable providers whose key VALUE is well-formed (mirrors BotConfig).
+
+    THE gating oracle wherever real key values are available (``should_warn_no_key``,
+    the env-backfill, config-store resolution). Stricter than
+    ``initializable_providers_with_keys`` (which is presence-only, for the resolver's
+    name-based path) — it also rejects placeholder / too-short values. Raw
+    ``providers_with_keys`` remains the DISPLAY oracle.
+    """
+    import os
+    env = os.environ if env is None else env
+    return [
+        p.name for p in PROFILES.values()
+        if p.initializable and looks_like_real_key(env.get(p.env_key))
+    ]
+
+
+def no_key_message() -> str:
+    """The single canonical no-key message (neutral module — no ``cli`` import).
+
+    Re-exported from ``cli.keys`` and reused by ``LLMManager._initialize``'s raise so
+    every no-key surface says the same thing.
+    """
+    return (
+        "No API key found. Run `polyrob init` to set one up, or put a provider key in "
+        "any of: process env, ./.polyrob/.env, ~/.polyrob/.env, root .env, "
+        "config/.env.development, or config/.env.production.\n"
+        "Supported providers: OPENROUTER_API_KEY (recommended), ANTHROPIC_API_KEY, "
+        "OPENAI_API_KEY, GEMINI_API_KEY, NVIDIA_API_KEY, DEEPSEEK_API_KEY "
+        "(direct client disabled — use OPENROUTER_API_KEY with model deepseek/deepseek-chat)."
+    )
+
+
+def get_profile(name: str) -> Optional[ProviderProfile]:
+    return PROFILES.get(name)
+
+
+def all_profiles() -> List[ProviderProfile]:
+    return list(PROFILES.values())

modules/llm/test_anthropic_cache_capture.py

@@ -0,0 +1,35 @@
+from types import SimpleNamespace
+from modules.llm.anthropic_client import AnthropicClient
+from modules.llm.model_registry import calculate_cost
+
+
+def _client_with_usage(**usage):
+    c = AnthropicClient.__new__(AnthropicClient)          # bypass __init__ (no network)
+    import logging; c.logger = logging.getLogger("t"); c.model_type = "claude-sonnet-4-5"
+    c.last_response = SimpleNamespace(usage=SimpleNamespace(**usage))
+    return c
+
+
+def test_anthropic_folds_cache_tokens_into_prompt_and_exposes_reads():
+    c = _client_with_usage(input_tokens=100, output_tokens=20,
+                           cache_read_input_tokens=900, cache_creation_input_tokens=50)
+    u = c._extract_usage_data()
+    assert u["prompt_tokens"] == 1050                     # 100 + 900 + 50
+    assert u["cached_tokens"] == 900                      # reads only
+    assert u["completion_tokens"] == 20
+
+
+def test_anthropic_no_cache_fields_unchanged():
+    # Old-shape usage (no cache attrs) must behave exactly as before.
+    c = _client_with_usage(input_tokens=100, output_tokens=20)
+    u = c._extract_usage_data()
+    assert u["prompt_tokens"] == 100 and u["completion_tokens"] == 20
+    assert u["total_tokens"] == 120
+    assert u.get("cached_tokens", 0) == 0
+
+
+def test_cost_uses_cached_rate_for_anthropic_reads():
+    # sonnet-4-5: input $3, cached $0.30 (after A1). 900 cached reads + 150 regular input.
+    cost = calculate_cost("claude-sonnet-4-5", input_tokens=1050, output_tokens=20, cached_tokens=900)
+    # regular = 1050-900 = 150 @ $3/M; cached = 900 @ $0.30/M
+    assert round(cost, 8) == round(150/1e6*3.0 + 900/1e6*0.3 + 20/1e6*15.0, 8)

modules/llm/test_cached_pricing_derivation.py

@@ -0,0 +1,24 @@
+"""Test that cached_input_price is derived per provider when not explicitly set."""
+
+from modules.llm.model_registry import get_model_config, ModelProvider
+
+
+def test_anthropic_cached_price_derived_at_10pct():
+    """Anthropic cache reads should be 10% of input price."""
+    m = get_model_config("claude-sonnet-4-5")
+    assert m.pricing.input_price == 3.0
+    assert m.pricing.cached_input_price == 0.3  # 0.1x
+
+
+def test_explicit_cached_price_is_preserved():
+    """DeepSeek sets 0.028 explicitly (model_registry.py:722) — must not be overwritten."""
+    m = get_model_config("deepseek-chat")
+    assert m.pricing.cached_input_price == 0.028
+
+
+def test_derivation_only_fills_none_and_matches_multiplier():
+    """All models should have cached_input_price derived or preserved."""
+    for name in ("claude-sonnet-4-5", "gpt-5"):
+        m = get_model_config(name)
+        assert m.pricing.cached_input_price is not None
+        assert m.pricing.cached_input_price <= m.pricing.input_price

modules/llm/think_scrubber.py

@@ -0,0 +1,444 @@
+"""Stateful scrubber for reasoning/thinking blocks in streamed assistant text.
+
+UP-07: ported essentially verbatim from Reference (`agent/think_scrubber.py`,
+the reference agent) — pure, zero-dependency. POLYROB wires it at the
+LLM-adapter content seam (modules/llm/adapters.py) so every provider's assistant text is
+scrubbed before it becomes an AIMessage. The legacy `agents/task/utils_json.py` regex
+strip stays for the fallback JSON-from-text path; this module covers the native seam and
+a broader tag set. See docs/plans/agent-upgrades-2026-06/UP-07-*.md.
+
+``run_agent._strip_think_blocks`` is regex-based and correct for a complete
+string, but when it runs *per-delta* in ``_fire_stream_delta`` it destroys
+the state that downstream consumers (CLI ``_stream_delta``, gateway
+``GatewayStreamConsumer._filter_and_accumulate``) rely on.
+
+Concretely, when MiniMax-M2.7 streams
+
+    delta1 = "<think>"
+    delta2 = "Let me check their config"
+    delta3 = "</think>"
+
+the per-delta regex erases delta1 entirely (case 2: unterminated-open at
+boundary matches ``^<think>...``), so the downstream state machine never
+sees the open tag, treats delta2 as regular content, and leaks reasoning
+to the user.  Consumers that don't run their own state machine (ACP,
+api_server, TTS) never had any defence at all — they just emitted
+whatever survived the upstream regex.
+
+This module centralises the tag-suppression state machine at the
+upstream layer so every stream_delta_callback sees text that has
+already had reasoning blocks removed.  Partial tags at delta
+boundaries are held back until the next delta resolves them, and
+end-of-stream flushing surfaces any held-back prose that turned out
+not to be a real tag.
+
+Usage::
+
+    scrubber = StreamingThinkScrubber()
+    for delta in stream:
+        visible = scrubber.feed(delta)
+        if visible:
+            emit(visible)
+    tail = scrubber.flush()  # at end of stream
+    if tail:
+        emit(tail)
+
+The scrubber is re-entrant per agent instance.  Call ``reset()`` at
+the top of each new turn so a hung block from an interrupted prior
+stream cannot taint the next turn's output.
+
+Tag variants handled (case-insensitive):
+  ``<think>``, ``<thinking>``, ``<reasoning>``, ``<thought>``,
+  ``<REASONING_SCRATCHPAD>``.
+
+Block-boundary rule for opens: an opening tag is only treated as a
+reasoning-block opener when it appears at the start of the stream,
+after a newline (optionally followed by whitespace), or when only
+whitespace has been emitted on the current line.  This prevents prose
+that *mentions* the tag name (e.g. ``"use <think> tags here"``) from
+being incorrectly suppressed.  Closed pairs (``<think>X</think>``) are
+always suppressed regardless of boundary; a closed pair is an
+intentional, bounded construct.
+"""
+
+from __future__ import annotations
+
+from typing import Tuple
+
+__all__ = ["StreamingThinkScrubber", "scrub_think_blocks"]
+
+
+def scrub_think_blocks(content: str) -> str:
+    """Scrub reasoning blocks from a COMPLETE assistant string (non-streaming).
+
+    Equivalent to feeding the whole string as one delta then flushing. Safe no-op when
+    there's no '<' (the overwhelming-majority fast path), so a non-reasoning completion
+    is never touched. Used by the adapter content seam where the whole completion arrives
+    at once (UP-07).
+    """
+    if not content or "<" not in content:
+        return content
+    s = StreamingThinkScrubber()
+    out = s.feed(content)
+    return out + s.flush()
+
+
+class StreamingThinkScrubber:
+    """Stateful scrubber for streaming reasoning/thinking blocks.
+
+    State machine:
+      - ``_in_block``: True while inside an opened block, waiting for
+        a close tag.  All text inside is discarded.
+      - ``_buf``: held-back partial-tag tail.  Emitted / discarded on
+        the next ``feed()`` call or by ``flush()``.
+      - ``_last_emitted_ended_newline``: True iff the most recent
+        emission to the consumer ended with ``\\n``, or nothing has
+        been emitted yet (start-of-stream counts as a boundary).  Used
+        to decide whether an open tag at buffer position 0 is at a
+        block boundary.
+    """
+
+    _OPEN_TAG_NAMES: Tuple[str, ...] = (
+        "think",
+        "thinking",
+        "reasoning",
+        "thought",
+        "REASONING_SCRATCHPAD",
+    )
+
+    # Materialise literal tag strings so the hot path does string
+    # operations, not regex compilation per feed().
+    _OPEN_TAGS: Tuple[str, ...] = tuple(f"<{name}>" for name in _OPEN_TAG_NAMES)
+    _CLOSE_TAGS: Tuple[str, ...] = tuple(f"</{name}>" for name in _OPEN_TAG_NAMES)
+
+    # Pre-compute the longest tag (for partial-tag hold-back bound).
+    _MAX_TAG_LEN: int = max(len(tag) for tag in _OPEN_TAGS + _CLOSE_TAGS)
+
+    def __init__(self) -> None:
+        self._in_block: bool = False
+        self._buf: str = ""
+        self._last_emitted_ended_newline: bool = True
+
+    def reset(self) -> None:
+        """Reset all state.  Call at the top of every new turn."""
+        self._in_block = False
+        self._buf = ""
+        self._last_emitted_ended_newline = True
+
+    def feed(self, text: str) -> str:
+        """Feed one delta; return the scrubbed visible portion.
+
+        May return an empty string when the entire delta is reasoning
+        content or is being held back pending resolution of a partial
+        tag at the boundary.
+        """
+        if not text:
+            return ""
+        buf = self._buf + text
+        self._buf = ""
+        out: list[str] = []
+
+        while buf:
+            if self._in_block:
+                # Hunt for the earliest close tag.
+                close_idx, close_len = self._find_first_tag(
+                    buf, self._CLOSE_TAGS,
+                )
+                if close_idx == -1:
+                    # No close yet — hold back a potential partial
+                    # close-tag prefix; discard everything else.
+                    held = self._max_partial_suffix(buf, self._CLOSE_TAGS)
+                    self._buf = buf[-held:] if held else ""
+                    return "".join(out)
+                # Found close: discard block content + tag, continue.
+                buf = buf[close_idx + close_len:]
+                self._in_block = False
+            else:
+                # Priority 1 — closed <tag>X</tag> pair anywhere in
+                # buf.  Closed pairs are always an intentional,
+                # bounded construct (even mid-line prose containing
+                # an open/close pair is almost certainly a model
+                # leaking reasoning inline), so no boundary gating.
+                pair = self._find_earliest_closed_pair(buf)
+                # Priority 2 — unterminated open tag at a block
+                # boundary.  Boundary-gated so prose that mentions
+                # '<think>' isn't over-stripped.
+                open_idx, open_len = self._find_open_at_boundary(
+                    buf, out,
+                )
+
+                # Pick whichever match comes earliest in the buffer.
+                if pair is not None and (
+                    open_idx == -1 or pair[0] <= open_idx
+                ):
+                    start_idx, end_idx = pair
+                    preceding = buf[:start_idx]
+                    if preceding:
+                        preceding = self._strip_orphan_close_tags(preceding)
+                        if preceding:
+                            out.append(preceding)
+                            self._last_emitted_ended_newline = (
+                                preceding.endswith("\n")
+                            )
+                    buf = buf[end_idx:]
+                    continue
+
+                if open_idx != -1:
+                    # Unterminated open at boundary — emit preceding,
+                    # enter block, continue loop with remainder.
+                    preceding = buf[:open_idx]
+                    if preceding:
+                        preceding = self._strip_orphan_close_tags(preceding)
+                        if preceding:
+                            out.append(preceding)
+                            self._last_emitted_ended_newline = (
+                                preceding.endswith("\n")
+                            )
+                    self._in_block = True
+                    buf = buf[open_idx + open_len:]
+                    continue
+
+                # No resolvable tag structure in buf.  Hold back any
+                # partial-tag prefix at the tail so a split tag
+                # across deltas isn't missed, then emit the rest.
+                held = self._max_partial_suffix(buf, self._OPEN_TAGS)
+                held_close = self._max_partial_suffix(
+                    buf, self._CLOSE_TAGS,
+                )
+                held = max(held, held_close)
+                if held:
+                    emit_text = buf[:-held]
+                    self._buf = buf[-held:]
+                else:
+                    emit_text = buf
+                    self._buf = ""
+                if emit_text:
+                    emit_text = self._strip_orphan_close_tags(emit_text)
+                    if emit_text:
+                        out.append(emit_text)
+                        self._last_emitted_ended_newline = (
+                            emit_text.endswith("\n")
+                        )
+                return "".join(out)
+
+        return "".join(out)
+
+    def flush(self) -> str:
+        """End-of-stream flush.
+
+        If still inside an unterminated block, held-back content is
+        discarded — leaking partial reasoning is worse than a
+        truncated answer.  Otherwise the held-back partial-tag tail is
+        emitted verbatim (it turned out not to be a real tag prefix).
+        """
+        if self._in_block:
+            self._buf = ""
+            self._in_block = False
+            return ""
+        tail = self._buf
+        self._buf = ""
+        if not tail:
+            return ""
+        tail = self._strip_orphan_close_tags(tail)
+        if tail:
+            self._last_emitted_ended_newline = tail.endswith("\n")
+        return tail
+
+    # ── internal helpers ───────────────────────────────────────────────
+
+    @staticmethod
+    def _find_first_tag(
+        buf: str, tags: Tuple[str, ...],
+    ) -> Tuple[int, int]:
+        """Return (earliest_index, tag_length) over *tags*, or (-1, 0).
+
+        Case-insensitive match.
+        """
+        buf_lower = buf.lower()
+        best_idx = -1
+        best_len = 0
+        for tag in tags:
+            idx = buf_lower.find(tag.lower())
+            if idx != -1 and (best_idx == -1 or idx < best_idx):
+                best_idx = idx
+                best_len = len(tag)
+        return best_idx, best_len
+
+    def _find_earliest_closed_pair(self, buf: str):
+        """Return (start_idx, end_idx) of the earliest closed pair, else None.
+
+        A closed pair is ``<tag>...</tag>`` of any variant.  Matches are
+        case-insensitive and non-greedy (the closest close tag after
+        an open tag wins), matching the regex ``<tag>.*?</tag>``
+        semantics of ``_strip_think_blocks`` case 1.  When two tag
+        variants could both match, the one whose open tag appears
+        earlier wins.
+        """
+        buf_lower = buf.lower()
+        best: "tuple[int, int] | None" = None
+        for open_tag, close_tag in zip(self._OPEN_TAGS, self._CLOSE_TAGS):
+            open_lower = open_tag.lower()
+            close_lower = close_tag.lower()
+            open_idx = buf_lower.find(open_lower)
+            if open_idx == -1:
+                continue
+            # P2-13: DEPTH-aware close matching. A nested same-variant block
+            # (<think>a<think>b</think>c</think>) used to match the FIRST inner close
+            # (non-greedy), which ended the block early and LEAKED the outer tail
+            # ("c") plus an orphan </think>. Count nested opens/closes and extend to
+            # the OUTER close. If the outer close isn't in the buffer yet (streaming,
+            # split mid-nest), matched_end stays -1 and we skip — the open-at-boundary
+            # / in-block path then handles it, same as an unterminated block.
+            depth = 1
+            pos = open_idx + len(open_lower)
+            matched_end = -1
+            while pos < len(buf_lower):
+                next_open = buf_lower.find(open_lower, pos)
+                next_close = buf_lower.find(close_lower, pos)
+                if next_close == -1:
+                    break  # no closing tag yet
+                if next_open != -1 and next_open < next_close:
+                    depth += 1
+                    pos = next_open + len(open_lower)
+                else:
+                    depth -= 1
+                    pos = next_close + len(close_lower)
+                    if depth == 0:
+                        matched_end = pos
+                        break
+            if matched_end == -1:
+                continue
+            if best is None or open_idx < best[0]:
+                best = (open_idx, matched_end)
+        return best
+
+    def _find_open_at_boundary(
+        self, buf: str, already_emitted: list[str],
+    ) -> Tuple[int, int]:
+        """Return the earliest block-boundary open-tag (idx, len).
+
+        Returns (-1, 0) if no boundary-legal opener is present.
+        """
+        buf_lower = buf.lower()
+        best_idx = -1
+        best_len = 0
+        for tag in self._OPEN_TAGS:
+            tag_lower = tag.lower()
+            search_start = 0
+            while True:
+                idx = buf_lower.find(tag_lower, search_start)
+                if idx == -1:
+                    break
+                if self._is_block_boundary(buf, idx, already_emitted):
+                    if best_idx == -1 or idx < best_idx:
+                        best_idx = idx
+                        best_len = len(tag)
+                    break  # first boundary hit for this tag is enough
+                search_start = idx + 1
+        return best_idx, best_len
+
+    def _is_block_boundary(
+        self, buf: str, idx: int, already_emitted: list[str],
+    ) -> bool:
+        """True iff position *idx* in *buf* is a block boundary.
+
+        A block boundary is:
+          - buf position 0 AND the most recent emission ended with
+            a newline (or nothing has been emitted yet)
+          - any position whose preceding text on the current line
+            (since the last newline in buf) is whitespace-only, AND
+            if there is no newline in the preceding buf portion, the
+            most recent prior emission ended with a newline
+        """
+        if idx == 0:
+            # Check whether the last already-emitted chunk in THIS
+            # feed() call ended with a newline, otherwise fall back
+            # to the cross-feed flag.
+            if already_emitted:
+                return already_emitted[-1].endswith("\n")
+            return self._last_emitted_ended_newline
+        preceding = buf[:idx]
+        last_nl = preceding.rfind("\n")
+        if last_nl == -1:
+            # No newline in buf before the tag — boundary only if the
+            # prior emission ended with a newline AND everything since
+            # is whitespace.
+            if already_emitted:
+                prior_newline = already_emitted[-1].endswith("\n")
+            else:
+                prior_newline = self._last_emitted_ended_newline
+            return prior_newline and preceding.strip() == ""
+        # Newline present — text between it and the tag must be
+        # whitespace-only.
+        return preceding[last_nl + 1:].strip() == ""
+
+    @classmethod
+    def _max_partial_suffix(
+        cls, buf: str, tags: Tuple[str, ...],
+    ) -> int:
+        """Return the longest buf-suffix that is a prefix of any tag.
+
+        Only prefixes strictly shorter than the tag itself count
+        (full-length suffixes are the tag and are handled as matches,
+        not held-back partials).  Case-insensitive.
+        """
+        if not buf:
+            return 0
+        buf_lower = buf.lower()
+        max_check = min(len(buf_lower), cls._MAX_TAG_LEN - 1)
+        for i in range(max_check, 0, -1):
+            suffix = buf_lower[-i:]
+            for tag in tags:
+                tag_lower = tag.lower()
+                if len(tag_lower) > i and tag_lower.startswith(suffix):
+                    return i
+        return 0
+
+    @classmethod
+    def _strip_orphan_close_tags(cls, text: str) -> str:
+        """Remove *boundary* orphan close tags from *text*.
+
+        An orphan close tag has no matching open in the current scrubber
+        state. It is stripped (with trailing whitespace) ONLY when it sits
+        at a block boundary — the start of the text or after a newline with
+        nothing but whitespace before it on that line. A close tag that
+        appears mid-prose (e.g. the assistant legitimately writing
+        ``"look for </think> in logs"`` or generating code/docs about
+        reasoning tags) is genuine output and is preserved verbatim.
+
+        Before boundary-gating, this stripped EVERY close tag unconditionally,
+        silently deleting legitimate prose that merely mentioned one.
+        """
+        if "</" not in text:
+            return text
+        text_lower = text.lower()
+        out: list[str] = []
+        i = 0
+        while i < len(text):
+            matched = False
+            if text_lower[i:i + 2] == "</":
+                for tag in cls._CLOSE_TAGS:
+                    tag_lower = tag.lower()
+                    tag_len = len(tag_lower)
+                    if text_lower[i:i + tag_len] != tag_lower:
+                        continue
+                    # Boundary gate: only an orphan close at the start of a
+                    # line (preceding text on this line is whitespace-only) is
+                    # treated as noise; mid-prose mentions are kept.
+                    emitted = "".join(out)
+                    last_nl = emitted.rfind("\n")
+                    line_prefix = emitted[last_nl + 1:] if last_nl != -1 else emitted
+                    if line_prefix.strip() != "":
+                        break  # mid-prose — keep the tag as literal text
+                    # Skip the tag and any trailing whitespace,
+                    # matching _strip_think_blocks case 3.
+                    j = i + tag_len
+                    while j < len(text) and text[j] in " \t\n\r":
+                        j += 1
+                    i = j
+                    matched = True
+                    break
+            if not matched:
+                out.append(text[i])
+                i += 1
+        return "".join(out)