Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

58.2 KB
Raw Blame
"""PEP 604 annotations must stay import-safe on Python 3.9 (requires-python >=3.9)."""

from __future__ import annotations

import bisect
import itertools
import json
import re

# Markerless forms are indistinguishable from quoted prose, so execution-class tools need a
# wrapper. Same rule for mcp__*. Must match the route's _LOCAL_CODE_TOOLS (drift test).
EXECUTION_CLASS_TOOL_NAMES = frozenset({"python", "terminal", "edit_file"})
_MCP_TOOL_PREFIX = "mcp__"


def _normalized_tool_name(name) -> str:
    """Strips the name as the controller's executor does, so the guard checks the name that will run."""
    return str(name).strip() if isinstance(name, str) else ""


def _markerless_promotable(name, enabled_tool_names) -> bool:
    """Bare calls named ``name`` may be promoted; execution-class and MCP names are refused."""
    name = _normalized_tool_name(name)
    if not name:
        return False
    if name in EXECUTION_CLASS_TOOL_NAMES or name.startswith(_MCP_TOOL_PREFIX):
        return False
    return enabled_tool_names is None or name in enabled_tool_names


def _markerless_execution_class(name) -> bool:
    """Execution-class or MCP name, ignoring enablement: what a body may contain must not vary."""
    name = _normalized_tool_name(name)
    return bool(name) and (name in EXECUTION_CLASS_TOOL_NAMES or name.startswith(_MCP_TOOL_PREFIX))


def _markerless_blocked_execution(name, enabled_tool_names) -> bool:
    """True for an enabled execution-class name: it keeps its chain place but loses promotion."""
    return _markerless_execution_class(name) and (
        enabled_tool_names is None or name in enabled_tool_names
    )


# One nesting level in the strip regexes; deeper may leak markup (still parsed).
_BRACKETED_JSON_ONE_LEVEL = r"\{[^{}]*(?:\{[^{}]*\}[^{}]*)*\}"

# group 1 = name for tool-list gating; the (?<!\[CALL_ID\]) lookbehind keeps the v11 call-id from reading as a name.
_REHEARSAL_CLOSED_STRIP_RE = re.compile(
    r"(?<!\[CALL_ID\])\b([\w-]+)\[ARGS\]\s*" + _BRACKETED_JSON_ONE_LEVEL, re.DOTALL
)
_REHEARSAL_TAIL_STRIP_RE = re.compile(r"(?<!\[CALL_ID\])\b([\w-]+)\[ARGS\]\s*(?:\{.*)?$", re.DOTALL)

# Named so _PAT_REQUIRED_TOKEN can skip a lazy rescan to EOF (quadratic).
_TC_JSON_CLOSED_PAT = re.compile(r"<tool_call>.*?</tool_call>", re.DOTALL)
_TC_GEMMA_CLOSED_PAT = re.compile(r"<\|tool_call>.*?<tool_call\|>", re.DOTALL)
# Dotted names too, matching the main parser, else TRUSTED spans miss <function=foo.bar>.
_TC_FUNC_CLOSED_PAT = re.compile(r"<function=[\w.-]+>.*?</function>", re.DOTALL)
_TOOL_CLOSED_PATS = [
    _TC_JSON_CLOSED_PAT,
    _TC_GEMMA_CLOSED_PAT,
    re.compile(r"<tool_call\|>"),
    _TC_FUNC_CLOSED_PAT,
    # Mirror the parser regexes: tolerate whitespace and v11 [CALL_ID]/[ARGS] metadata.
    re.compile(
        r"\[TOOL_CALLS\]\s*[\w-]+(?:\[CALL_ID\][\w-]+)?(?:\[ARGS\])?\s*"
        + _BRACKETED_JSON_ONE_LEVEL,
        re.DOTALL,
    ),
    _REHEARSAL_CLOSED_STRIP_RE,
    # Drop the bare v11 [/TOOL_CALLS] closer the balanced scan leaves behind.
    re.compile(r"\[/TOOL_CALLS\]"),
]
# The rehearsal tail needs "{" or EOF so prose foo[ARGS] survives.
_TOOL_OPEN_XML_TAIL_PATS = [
    re.compile(r"<tool_call>.*$", re.DOTALL),
    re.compile(r"<\|tool_call>.*$", re.DOTALL),
    re.compile(r"<function=[\w-]+>.*$", re.DOTALL),
]
_TOOL_ALL_PATS = (
    _TOOL_CLOSED_PATS
    + _TOOL_OPEN_XML_TAIL_PATS
    + [
        re.compile(r"\[TOOL_CALLS\].*$", re.DOTALL),
        _REHEARSAL_TAIL_STRIP_RE,
    ]
)

# Rehearsal strips (name in group 1); name-gated via ``enabled_tool_names``, strip-all when None.
_REHEARSAL_STRIP_PATS = frozenset({_REHEARSAL_CLOSED_STRIP_RE, _REHEARSAL_TAIL_STRIP_RE})

# Stripped before the Gemma helper so a quoted Gemma opener cannot truncate the block.
_TOOL_CLOSED_BLOCK_PATS = [_TC_JSON_CLOSED_PAT, _TC_FUNC_CLOSED_PAT]
# Skip the closed-pair pass if the close token is absent; a lazy match rescans to EOF per opener.
_PAT_REQUIRED_TOKEN = {
    # Callers bound at the LAST required CLOSER unconditionally; a gap test for openers is quadratic.
    _TC_JSON_CLOSED_PAT: ("</tool_call>", "<tool_call>"),
    _TC_GEMMA_CLOSED_PAT: ("<tool_call|>", "<|tool_call>"),
    _TC_FUNC_CLOSED_PAT: ("</function>", "<function="),
    # Literal replacements skip the sub and its _code_spans scan when there is no rehearsal.
    _REHEARSAL_CLOSED_STRIP_RE: "[ARGS]",
    _REHEARSAL_TAIL_STRIP_RE: "[ARGS]",
}


def strip_tool_patterns(text: str, patterns) -> str:
    """Apply ``patterns`` in order, skipping closed-pair passes with no close token."""
    for pat in patterns:
        required = _PAT_REQUIRED_TOKEN.get(pat)
        if isinstance(required, tuple):
            token, opener = required
            first_opener = text.find(opener)
            if first_opener < 0:
                continue
            last_close = text.rfind(token)
            if last_close < 0:
                continue
            scan_end = last_close + len(token)
            if scan_end == len(text):
                text = pat.sub("", text)
            else:
                text = pat.sub("", text[:scan_end]) + text[scan_end:]
        else:
            if required is not None and required not in text:
                continue
            text = pat.sub("", text)
    return text


def _rehearsal_strip(m, pat, text, spans, enabled_tool_names) -> str:
    """Strip from a later real call on, but never from inside the kept call args, or its tail is cut."""
    if _markerless_promotable(m.group(1), enabled_tool_names) and not _in_code(spans, m.start()):
        return ""
    # Resolved lazily: this scans the whole body, which made long blocked streams quadratic.
    reh = _REHEARSAL_RE.search(text, m.start(), m.end())
    cached_body_end: list = []

    def body_end():
        if not cached_body_end:
            cached_body_end.append(
                _balanced_json_span(text, reh.end()) if reh is not None else None
            )
        return cached_body_end[0]

    pos = m.start()
    while True:
        nxt = pat.search(text, pos + 1)
        if nxt is None or nxt.start() >= m.end():
            return m.group(0)
        if (
            (body_end() is None or nxt.start() > body_end())
            and not _in_code(spans, nxt.start())
            and _markerless_promotable(nxt.group(1), enabled_tool_names)
        ):
            return m.group(0)[: nxt.start() - m.start()]
        pos = nxt.start()


def apply_tool_strip_patterns(
    text: str,
    patterns,
    enabled_tool_names = None,
) -> str:
    """Skips a closed-pair pattern whose close token is absent, keeping unclosed streams linear."""
    for pat in patterns:
        required = _PAT_REQUIRED_TOKEN.get(pat)
        scan_end = len(text)
        if isinstance(required, tuple):
            token, opener = required
            first_opener = text.find(opener)
            if first_opener < 0:
                continue
            last_close = text.rfind(token)
            if last_close < 0:
                continue
            scan_end = last_close + len(token)
        elif required is not None and required not in text:
            continue
        if pat in _REHEARSAL_STRIP_PATS:
            # Same two gates as the parser's _iter_bracket_spans, so unpromoted rehearsals stay visible.
            spans = _code_spans(text)
            _t = text
            text = pat.sub(lambda m: _rehearsal_strip(m, pat, _t, spans, enabled_tool_names), text)
        else:
            text = pat.sub("", text[:scan_end]) + text[scan_end:]
    return text


# TML Inkling's native call marker: JSON uses "args", block closes with <|end_message|>.
_TC_JSON_START_RE = re.compile(r"(?:<tool_call>|<\|content_invoke_tool_json\|>)\s*\{")
_TC_GEMMA_START_RE = re.compile(r"<\|tool_call>\s*call\s*:\s*([\w.\-]+)\s*\{")
_TC_FUNC_START_RE = re.compile(r"<function=([\w-]+)>\s*")
_TC_END_TAG_RE = re.compile(r"</tool_call>|<\|end_message\|>")
_TC_GEMMA_END_TAG_RE = re.compile(r"<tool_call\|>")
_TC_FUNC_CLOSE_RE = re.compile(r"\s*</function>\s*$")
# Horizontal-whitespace trailing class keeps the wrapping newline; _trim_param_value trims it.
_TC_PARAM_START_RE = re.compile(r"<parameter=([\w-]+)>[^\S\n]*")
_TC_PARAM_CLOSE_RE = re.compile(r"\s*</parameter>\s*$")
_GEMMA_QUOTE = '<|"|>'
_PARAM_CLOSE_TAG = "</parameter>"
_FUNC_CLOSE_TAG = "</function>"
_WRAP_OPEN_RE = re.compile(r"<tool_call>\s*$")
_WRAP_CLOSE_RE = re.compile(r"\s*</tool_call>")
# A comma not followed by a key token is part of a bare Gemma value (New York, NY).
_GEMMA_NEXT_KEY_RE = re.compile(r"\s*[A-Za-z_][\w.\-]*\s*:")

# A candidate starting inside a think block is a rehearsal; "$" accepts an unclosed block mid-stream.
_THINK_TAG_RE = re.compile(r"<think>.*?(?:</think>|$)|\[THINK\].*?(?:\[/THINK\]|$)", re.DOTALL)
# Bare open/close markers for prefilled-reasoning turns (template opens <think> in the prompt).
_THINK_OPEN_RE = re.compile(r"<think>|\[THINK\]")
_THINK_CLOSE_RE = re.compile(r"</think>|\[/THINK\]")

# Mistral canonical array: [TOOL_CALLS] + JSON list of {"name","arguments"} objects.
_MISTRAL_ARRAY_RE = re.compile(r"\[TOOL_CALLS\]\s*(?=\[)")

# [CALL_ID] is metadata, not the name, and hyphens keep dashed MCP names whole.
_MISTRAL_BRACKET_RE = re.compile(
    r"\[TOOL_CALLS\]\s*([\w-]+)(?:\[CALL_ID\][\w-]+)?(?:\[ARGS\])?\s*(?=\{)"
)

# The lookbehind keeps the v11 call-id from being taken as the function name.
_REHEARSAL_RE = re.compile(r"(?<!\[CALL_ID\])\b([\w-]+)\[ARGS\]\s*(?=\{)")

# Gates only the markerless rehearsal form, so quoted syntax stays text. Inline runs are
# enumerated by length, not backreferenced: (`+)..\1 backtracks catastrophically.
_CODE_SPAN_RE = re.compile(
    r"^[ \t]*(?:>[ \t]*)*(?:"
    r"(?P<bt>```+)[^`\n]*$.*?(?:^[ \t]*(?:>[ \t]*)*(?P=bt)`*[ \t\r]*$|\Z)"
    r"|(?P<tl>~~~+)[^\n]*$.*?(?:^[ \t]*(?:>[ \t]*)*(?P=tl)~*[ \t\r]*$|\Z))"
    r"|``(?:[^`]|`(?!`))*?``|`[^`\n]*`",
    re.DOTALL | re.MULTILINE,
)

# A single tool tag (and at most a name) alone in an inline code span (`<tool_call>`, `[TOOL_CALLS]name`) names the
# format: no call body fits inside. No lookahead past the closing run, so append-only growth never revokes a match.
# Runs of three or more are fences; reasoning tags decide the think segmentation, not a call.
_TAG_MENTION_RE = re.compile(
    r"(?<!`)(``?)[ \t]*("
    r"<(?!/?think(?:ing)?>)[^<>`\n]+>[\w.\-]*"
    r"|\[/?(?:TOOL_CALLS|ARGS|CALL_ID)\][\w.\-]*"
    r")[ \t]*\1"
)
# Any tag still pairs its backticks above, but only tool-call families are returned: masking `<div>` changes no strip
# output. A match never crosses a newline, so pairing restarts per line and only lines holding a tool tag are scanned.
_TOOL_TAG_PREFIXES = (
    "<tool",
    "</tool",
    "<function",
    "</function",
    "<param",
    "</param",
    "<arg_",
    "</arg_",
    "<minimax:",
    "</minimax:",
    "<|",
    "<|",
    "[",
)
_TOOL_TAG_HINT_RE = re.compile(
    r"</?(?:tool|function|param|arg_|minimax:)|<[||]|\[/?(?:TOOL_CALLS|ARGS|CALL_ID)\]"
)


def tag_mention_spans(text: str) -> list[tuple[int, int]]:
    """Ordered spans of the tag inside each lone-tag inline code span (backticks excluded)."""
    if "`" not in text:
        return []
    spans = []
    line_end = 0
    for hint in _TOOL_TAG_HINT_RE.finditer(text):
        if hint.start() < line_end:
            continue
        line_start = text.rfind("\n", 0, hint.start()) + 1
        line_end = text.find("\n", hint.end())
        if line_end < 0:
            line_end = len(text)
        spans.extend(
            m.span(2)
            for m in _TAG_MENTION_RE.finditer(text, line_start, line_end)
            if m.group(2).startswith(_TOOL_TAG_PREFIXES)
        )
    if not spans:
        return spans
    # One inside a real call (found with the mentions blanked, so none reads as an opener) is that call's data:
    # masking it would let the call's strip swallow a mask and drop every mention's protection.
    parts, prev = [], 0
    for start, end in spans:
        parts.append(text[prev:start])
        parts.append(" " * (end - start))
        prev = end
    parts.append(text[prev:])
    calls = _tool_call_markup_spans("".join(parts))
    if not calls:
        return spans
    return [s for s in spans if not any(cs <= s[0] < ce for cs, ce in calls)]


def in_tag_mention(spans, pos: int) -> bool:
    """Whether ``pos`` falls in one of ``tag_mention_spans`` (a span may start at ``pos``)."""
    i = bisect.bisect_right(spans, (pos, float("inf"))) - 1
    return i >= 0 and spans[i][0] <= pos < spans[i][1]


# Above this size skip the balanced scan; the linear regex catch-all bounds pathological output.
_MAX_BRACKET_SCAN_CHARS = 1_000_000


def _balanced_json_span(text: str, start: int) -> int | None:
    """End index of the balanced JSON object at start, or None; honors escapes and strings."""
    if start >= len(text) or text[start] != "{":
        return None
    # A span only closes on "}"; the streaming path rescans a growing body, and find runs in C.
    if text.find("}", start) < 0:
        return None
    depth = 0
    in_string = False
    escape = False
    for j in range(start, len(text)):
        ch = text[j]
        if escape:
            escape = False
            continue
        if ch == "\\":
            escape = True
            continue
        if in_string:
            if ch == '"':
                in_string = False
            continue
        if ch == '"':
            in_string = True
        elif ch == "{":
            depth += 1
        elif ch == "}":
            depth -= 1
            if depth == 0:
                return j
    return None


# Unrolled loops with nothing after them never backtrack; possessive quantifiers need Python 3.11+.
_BRACE_SKIP_RE = re.compile(r'[^"{}]*')
_BRACE_SKIP_GEMMA_RE = re.compile(r'[^"{}<]*(?:<(?!\|"\|>)[^"{}<]*)*')
_JSON_STRING_BODY_RE = re.compile(r'[^"\\]*(?:\\.[^"\\]*)*', re.DOTALL)


def _balanced_brace_end(
    content: str,
    brace_start: int,
    *,
    gemma_quotes: bool = False,
) -> int | None:
    """Index of the brace matching brace_start, or None; shared with core/inference/tool_call_parser.py."""
    if brace_start >= len(content) or content[brace_start] != "{":
        return None
    n = len(content)
    skip = _BRACE_SKIP_GEMMA_RE.match if gemma_quotes else _BRACE_SKIP_RE.match
    string_body = _JSON_STRING_BODY_RE.match
    depth = 0
    i = brace_start
    while i < n:
        i = skip(content, i).end()
        if i >= n:
            return None
        ch = content[i]
        if ch == "<":
            close = content.find(_GEMMA_QUOTE, i + len(_GEMMA_QUOTE))
            if close < 0:
                return None
            i = close + len(_GEMMA_QUOTE)
            continue
        if ch == '"':
            i = string_body(content, i + 1).end()
            # The body stops at the closing quote, at the end, or before a trailing lone backslash.
            if i >= n or content[i] != '"':
                return None
            i += 1
            continue
        if ch == "{":
            depth += 1
        else:
            depth -= 1
            if depth == 0:
                return i
        i += 1
    return None


def _balanced_bracket_end(
    src: str,
    start: int,
    *,
    braces_count: bool = True,
) -> int | None:
    """Braces count toward the same depth, so a truncated object cannot close an array early."""
    if start >= len(src) or src[start] != "[":
        return None
    openers = "[{" if braces_count else "["
    closers = "]}" if braces_count else "]"
    depth = 0
    i = start
    in_string = False
    while i < len(src):
        ch = src[i]
        if in_string:
            if ch == "\\" and i + 1 < len(src):
                i += 2
                continue
            if ch == '"':
                in_string = False
        elif ch == '"':
            in_string = True
        elif ch in openers:
            depth += 1
        elif ch in closers:
            depth -= 1
            if depth == 0:
                return i
        i += 1
    return None


def _decode_array_items(text: str, body_start: int, body_end: int):
    """Decodes element by element with raw_decode: json.loads rejects the comma-less {...}{...} form."""
    decoder = json.JSONDecoder()
    objs: list = []
    ends: list[int] = []
    i = text.find("[", body_start)
    if i < 0:
        return objs, ends
    i += 1
    while i < body_end:
        while i < body_end and text[i] in " \t\r\n,":
            i += 1
        if i >= body_end or text[i] == "]":
            break
        try:
            obj, rel = decoder.raw_decode(text[i:body_end])
        except (json.JSONDecodeError, ValueError):
            break
        i += rel
        objs.append(obj)
        ends.append(i)
    return objs, ends


def _code_spans(text: str, start: int = 0) -> list[tuple[int, int]]:
    """Returns ordered, non-overlapping spans so _in_code can bisect them instead of rescanning."""
    if "`" not in text and "~~~" not in text:
        return []
    return [m.span() for m in _CODE_SPAN_RE.finditer(text, start)]


def _in_code(spans, pos: int) -> bool:
    """Whether ``pos`` falls in one of ``spans`` (ordered, non-overlapping)."""
    i = bisect.bisect_right(spans, (pos, pos)) - 1
    return i >= 0 and spans[i][0] <= pos < spans[i][1]


def _iter_bracket_spans(
    text: str,
    start: int = 0,
    enabled_tool_names = None,
):
    """Bare name[ARGS]{..} is a call only for a promotable name outside code; [TOOL_CALLS] always counts."""
    n = len(text)
    specs = (
        ("array", _MISTRAL_ARRAY_RE),
        ("name", _MISTRAL_BRACKET_RE),
        ("rehearsal", _REHEARSAL_RE),
    )
    # Each regex needs its case-sensitive literal tag, so str.find gates it exactly.
    has_calls_tag = text.find("[TOOL_CALLS]", start) >= 0
    nexts = {
        "array": _MISTRAL_ARRAY_RE.search(text, start) if has_calls_tag else None,
        "name": _MISTRAL_BRACKET_RE.search(text, start) if has_calls_tag else None,
        "rehearsal": (
            _REHEARSAL_RE.search(text, start) if text.find("[ARGS]", start) >= 0 else None
        ),
    }
    if not any(nexts.values()):
        return
    last_brace_close = text.rfind("}")
    last_array_close = max(text.rfind("]"), last_brace_close)
    cursor = start
    code_spans: list | None = None
    while cursor < n:
        for kind, rx in specs:
            m = nexts[kind]
            if m is not None and m.start() < cursor:
                nexts[kind] = rx.search(text, cursor)
        live = [(kind, m) for kind, m in nexts.items() if m is not None]
        if not live:
            return
        kind, m = min(live, key = lambda km: km[1].start())
        last_close = last_array_close if kind == "array" else last_brace_close
        if m.end() > last_close:
            # Keep other formats live, but skip a balanced scan to EOF per doomed opener.
            nexts[kind] = None
            # Truncated body: skip and keep scanning; the caller's catch-all strips the tail.
            cursor = m.end()
            continue
        if kind == "array":
            end = _balanced_bracket_end(text, m.end())
        else:
            end = _balanced_json_span(text, m.end())
        if end is None:
            cursor = m.end()
            continue
        if kind == "rehearsal" and not _markerless_promotable(m.group(1), enabled_tool_names):
            # Quoted syntax, not a call: advance past its body without yielding.
            cursor = end + 1
            continue
        if kind == "rehearsal":
            if code_spans is None:
                code_spans = _code_spans(text)
            if _in_code(code_spans, m.start()):
                cursor = end + 1
                continue
        yield (m.start(), end + 1, kind, m)
        cursor = end + 1


def _split_top_level_commas(src: str) -> list:
    """Split on commas that are not inside a nested ``[]``/``{}`` or a string."""
    parts: list[str] = []
    depth = 0
    in_string = False
    start = 0
    i = 0
    while i < len(src):
        ch = src[i]
        if in_string:
            if ch == "\\" and i + 1 < len(src):
                i += 2
                continue
            if ch == '"':
                in_string = False
        elif ch == '"':
            in_string = True
        elif ch in "[{":
            depth += 1
        elif ch in "]}":
            depth -= 1
        elif ch == "," and depth == 0:
            parts.append(src[start:i])
            start = i + 1
        i += 1
    parts.append(src[start:])
    return parts


def _quote_gemma_array_elements(body: str) -> str:
    """Quotes bare Gemma array elements, since unquoted labels:[bug,ui] would make json.loads fail."""
    out: list[str] = []
    for element in _split_top_level_commas(body):
        stripped = element.strip()
        if not stripped or stripped[0] == '"':
            out.append(element)
            continue
        if stripped[0] == "{":
            # Object element: quote its keys/bare values like a top-level object.
            out.append(_quote_gemma_object_keys(stripped))
            continue
        if stripped[0] == "[":
            # Nested array: normalise its elements too.
            inner_end = _balanced_bracket_end(stripped, 0)
            if inner_end == len(stripped) - 1:
                out.append("[" + _quote_gemma_array_elements(stripped[1:inner_end]) + "]")
            else:
                out.append(element)
            continue
        try:
            json.loads(stripped)
            out.append(element)
        except (json.JSONDecodeError, ValueError):
            out.append(json.dumps(stripped))
    return ",".join(out)


def _normalise_gemma_quoted_strings(src: str) -> str:
    parts: list[str] = []
    i = 0
    while i < len(src):
        if not src.startswith(_GEMMA_QUOTE, i):
            parts.append(src[i])
            i += 1
            continue
        end = src.find(_GEMMA_QUOTE, i + len(_GEMMA_QUOTE))
        if end < 0:
            parts.append(src[i:])
            break
        raw_value = src[i + len(_GEMMA_QUOTE) : end]
        parts.append(json.dumps(raw_value))
        i = end + len(_GEMMA_QUOTE)
    return "".join(parts)


def _quote_gemma_object_keys(src: str) -> str:
    parts: list[str] = []
    i = 0
    in_string = False
    while i < len(src):
        ch = src[i]
        if in_string:
            parts.append(ch)
            if ch == "\\" and i + 1 < len(src):
                parts.append(src[i + 1])
                i += 2
                continue
            if ch == '"':
                in_string = False
            i += 1
            continue
        if ch == '"':
            in_string = True
            parts.append(ch)
            i += 1
            continue
        if ch not in "{,":
            parts.append(ch)
            i += 1
            continue

        parts.append(ch)
        i += 1
        key_start = i
        while i < len(src) and src[i].isspace():
            i += 1
        key_name_start = i
        while i < len(src) and (src[i].isalnum() or src[i] in "_-."):
            i += 1
        key_name = src[key_name_start:i]
        colon_pos = i
        while colon_pos < len(src) and src[colon_pos].isspace():
            colon_pos += 1
        if key_name and colon_pos < len(src) and src[colon_pos] == ":":
            parts.append(src[key_start:key_name_start])
            parts.append(json.dumps(key_name))
            parts.append(src[i:colon_pos])
            parts.append(":")
            i = colon_pos + 1
            # Gemma may emit bare string values ({unit:celsius}); quote them so json.loads succeeds.
            ws = i
            while i < len(src) and src[i].isspace():
                i += 1
            parts.append(src[ws:i])
            if i < len(src) and src[i] == "[":
                # Quote bare array elements (labels:[bug,ui]) so json.loads succeeds instead of dropping the call.
                arr_end = _balanced_bracket_end(src, i)
                if arr_end is None:
                    parts.append(src[i:])
                    i = len(src)
                else:
                    parts.append("[" + _quote_gemma_array_elements(src[i + 1 : arr_end]) + "]")
                    i = arr_end + 1
            elif i < len(src) and src[i] not in '"{':
                v_start = i
                # A comma inside the value (New York, NY) does not terminate it.
                while i < len(src):
                    if src[i] == "}":
                        break
                    if src[i] == "," and _GEMMA_NEXT_KEY_RE.match(src, i + 1):
                        break
                    i += 1
                raw = src[v_start:i]
                try:
                    json.loads(raw.strip())
                    parts.append(raw)
                except (json.JSONDecodeError, ValueError):
                    # Empty ({k:}) becomes "" so json.loads sees {"k":""} and not invalid {"k":}.
                    parts.append(json.dumps(raw.strip()))
        else:
            parts.append(src[key_start:i])
    return "".join(parts)


def _gemma_arguments_to_json(args_src: str) -> dict:
    """Parse Gemma 4's native call:name{key:value} argument object."""
    args_src = args_src.strip()
    if not args_src:
        return {}
    src = _normalise_gemma_quoted_strings(args_src)
    src = "{" + src + "}"
    src = _quote_gemma_object_keys(src)
    return json.loads(src)


def _inside_open_parameter(
    content: str,
    pos: int,
    *,
    param_start_re = None,
    param_closers = (_PARAM_CLOSE_TAG,),
    func_closers = (_FUNC_CLOSE_TAG,),
) -> bool:
    """True when pos is inside an unclosed parameter value; shared with tool_call_parser.py"""
    if param_start_re is None:
        param_start_re = _TC_PARAM_START_RE
    last_param_start = -1
    # Search backwards to the nearest <param candidate instead of rescanning the whole prefix per marker.
    reverse_param_search = (
        param_start_re is _TC_PARAM_START_RE
        or param_start_re.pattern.startswith(r"<(?:parameter|param)")
    )
    if reverse_param_search:
        candidate = content.rfind("<param", 0, pos)
        while candidate >= 0:
            match = param_start_re.match(content, candidate, pos)
            if match is not None:
                last_param_start = candidate
                break
            candidate = content.rfind("<param", 0, candidate)
    else:
        for match in param_start_re.finditer(content, 0, pos):
            last_param_start = match.start()
    if last_param_start < 0:
        return False
    # The parameter's OWN close tag decides; bounded so an absent spelling skips the suffix scan.
    for tag in param_closers:
        found = content.find(tag, last_param_start, min(len(content), pos + len(tag)))
        if 0 <= found <= pos:
            return False
    # Try the matching closer first; cross-spelling closes still work but need a longer scan.
    if content.startswith("<param", last_param_start) and not content.startswith(
        "<parameter", last_param_start
    ):
        param_closers = tuple(reversed(param_closers))
    if any(content.find(tag, pos + 1) >= 0 for tag in param_closers):
        return True
    # With no parameter close anywhere, a later close and no close both mean still inside.
    for tag in func_closers:
        found = content.find(tag, last_param_start, min(len(content), pos + len(tag)))
        if 0 <= found <= pos:
            return False
    return True


# A few direct scans beat building an index on the per-token streaming strip; past them the index wins.
_OPEN_PARAMETER_SCAN_LIMIT = 16


class _OpenParameterIndex:
    """``_inside_open_parameter`` for many offsets of one text by bisecting sorted tag offsets (per-call
    scans were quadratic). Valid only for ``<parameter``/``<param`` openers, as the reverse search is."""

    __slots__ = (
        "_content",
        "_param_start_re",
        "_param_closer_tags",
        "_func_closer_tags",
        "_scans",
        "_param_starts",
        "_param_ends",
        "_param_closers",
        "_func_closers",
    )

    def __init__(
        self,
        content: str,
        *,
        param_start_re = None,
        param_closers = (_PARAM_CLOSE_TAG,),
        func_closers = (_FUNC_CLOSE_TAG,),
    ):
        self._content = content
        self._param_start_re = _TC_PARAM_START_RE if param_start_re is None else param_start_re
        self._param_closer_tags = param_closers
        self._func_closer_tags = func_closers
        self._scans = 0
        self._param_starts = None

    def _build(self) -> None:
        content = self._content
        starts = [m.start() for m in self._param_start_re.finditer(content)]
        self._param_starts = starts
        # Bounded at the tag's own ">", as the helper's endpos-limited match is.
        self._param_ends = [content.index(">", start) + 1 for start in starts]
        self._param_closers = self._positions(content, self._param_closer_tags)
        self._func_closers = self._positions(content, self._func_closer_tags)

    @staticmethod
    def _positions(content: str, tags) -> list[int]:
        found: list[int] = []
        for tag in tags:
            at = content.find(tag)
            while at >= 0:
                found.append(at)
                at = content.find(tag, at + 1)
        return sorted(found)

    def inside(self, pos: int) -> bool:
        if self._param_starts is None:
            if self._scans < _OPEN_PARAMETER_SCAN_LIMIT:
                self._scans += 1
                return _inside_open_parameter(
                    self._content,
                    pos,
                    param_start_re = self._param_start_re,
                    param_closers = self._param_closer_tags,
                    func_closers = self._func_closer_tags,
                )
            self._build()
        idx = bisect.bisect_right(self._param_ends, pos) - 1
        if idx < 0:
            return False
        last = self._param_starts[idx]
        closers = self._param_closers
        i = bisect.bisect_left(closers, last)
        if i < len(closers) and closers[i] <= pos:
            return False
        if closers and closers[-1] > pos:
            return True
        closers = self._func_closers
        i = bisect.bisect_left(closers, last)
        return not (i < len(closers) and closers[i] <= pos)


def _func_close_index(
    content: str,
    body_start: int,
    body: str,
    *,
    inside = None,
) -> int:
    """First close outside a parameter value; taking the last one swallowed prose after the real close."""
    if inside is None:
        inside = lambda pos: _inside_open_parameter(content, pos)  # noqa: E731
    idx = body.find(_FUNC_CLOSE_TAG)
    while idx >= 0:
        if not inside(body_start + idx):
            return idx
        idx = body.find(_FUNC_CLOSE_TAG, idx + 1)
    return -1


def _trim_param_value(val: str) -> str:
    """Trims only the one wrapping newline; strip() would destroy code and diff indentation."""
    if val.startswith("\n"):
        val = val[1:]
    if val.endswith("\n"):
        val = val[:-1]
    return val


def _json_object_body(body: str) -> dict | None:
    """Arguments of a Hermes/XML mix ``<function=NAME>{json}</function>``; a heal, so Auto-Heal only."""
    if not body.lstrip().startswith("{"):
        return None
    try:
        value = json.loads(body)
    except (ValueError, RecursionError):
        return None
    return value if isinstance(value, dict) else None


def _marker_coverage(content: str, markers) -> list[tuple[int, int]]:
    """Unbalanced braces cover to EOF; a closeless balanced call covers only braces, so siblings survive."""
    n = len(content)
    brace_regions = sorted((s, be) for (s, be, _k, _m) in markers if be >= 0)
    brace_starts = []
    brace_max_ends = []
    if len(brace_regions) >= 8:
        brace_starts = [s for s, _be in brace_regions]
        max_end = -1
        for _s, be in brace_regions:
            max_end = max(max_end, be)
            brace_max_ends.append(max_end)
    events = []
    for idx, (_start, brace_end, _kind, _m) in enumerate(markers):
        if brace_end >= 0:
            events.append((brace_end, 0, _kind, idx))
    for kind, close_re in (("json", _TC_END_TAG_RE), ("gemma", _TC_GEMMA_END_TAG_RE)):
        for cm in close_re.finditer(content):
            # A close inside another call's braces is quoted data and must not pop an earlier marker.
            if brace_starts:
                region_idx = bisect.bisect_left(brace_starts, cm.start()) - 1
                inside_braces = region_idx >= 0 and cm.start() < brace_max_ends[region_idx]
            else:
                inside_braces = any(s < cm.start() < be for s, be in brace_regions)
            if inside_braces:
                continue
            events.append((cm.start(), 1, kind, cm.end()))
    events.sort(key = lambda e: (e[0], e[1]))
    waiting = {"json": [], "gemma": []}
    close_end_for: dict[int, int] = {}
    for _pos, order, kind, payload in events:
        if order == 0:
            waiting[kind].append(payload)
        elif waiting[kind]:
            close_end_for[waiting[kind].pop()] = payload
    coverage = []
    for idx, (start, brace_end, _kind, _m) in enumerate(markers):
        if brace_end < 0:
            coverage.append((start, n))
        elif idx in close_end_for:
            coverage.append((start, close_end_for[idx]))
        else:
            coverage.append((start, brace_end))
    return coverage


def _build_markers(content: str):
    """Markers as ``(start, brace_end, kind, match)`` in order; brace_end < 0 means unclosed."""
    markers = []
    candidates = []
    for start_re, gemma, kind in (
        (_TC_JSON_START_RE, False, "json"),
        (_TC_GEMMA_START_RE, True, "gemma"),
    ):
        for m in start_re.finditer(content):
            candidates.append((m, gemma, kind))
    many_candidates = len(candidates) > 1
    has_parameter = "<parameter=" in content if many_candidates else True
    last_brace = content.rfind("}") if many_candidates else None
    inside = _OpenParameterIndex(content).inside
    for m, gemma, kind in candidates:
        if has_parameter and inside(m.start()):
            continue
        brace_start = m.end() - 1
        brace_end = (
            _balanced_brace_end(content, brace_start, gemma_quotes = gemma)
            if last_brace is None or brace_start < last_brace
            else None
        )
        # Keep the ``-1`` sentinel: ``marker_coverage`` consumers test ``brace_end < 0``.
        markers.append((m.start(), -1 if brace_end is None else brace_end, kind, m))
    markers.sort(key = lambda c: c[0])
    return markers


def marker_coverage(content: str) -> list[tuple[int, int]]:
    """Spans of JSON/Gemma tool markers, even a marker that failed to parse, so other parsers treat
    markup inside as that call's data rather than a sibling call."""
    return _marker_coverage(content, _build_markers(content))


def _is_strict_json(text: str) -> bool:
    try:
        json.loads(text)
    except (json.JSONDecodeError, ValueError):
        return False
    return True


def _glued_call_objects(content: str, pos: int, end: int):
    """Call objects glued after a parsed one inside the same ``<tool_call>``, up to its paired close at
    ``end``: ``[(start, name, arguments_json)]``, or None unless every object between is a strict
    ``{"name": .., "arguments"|"parameters": {..}}`` and only whitespace separates them and the close.
    Braces are matched outside JSON strings, so a ``}{`` or closing tag inside an argument never splits
    a call; the window is this marker's own coverage, so the scan stays linear."""
    close_m = _TC_END_TAG_RE.search(content, pos, end)
    if close_m is None or close_m.end() != end:
        return None
    window = content[pos : close_m.start()]
    out = []
    i = 0
    n = len(window)
    while True:
        while i < n and window[i] in " \t\r\n":
            i += 1
        if i >= n:
            break
        if window[i] != "{":
            return None
        obj_end = _balanced_brace_end(window, i)
        if obj_end is None:
            return None
        try:
            obj = json.loads(window[i : obj_end + 1])
        except (json.JSONDecodeError, ValueError):
            return None
        if not isinstance(obj, dict):
            return None
        g_name = obj.get("name")
        g_args = obj.get("arguments") if "arguments" in obj else obj.get("parameters")
        if not isinstance(g_name, str) or not g_name or not isinstance(g_args, dict):
            return None
        out.append((pos + i, g_name, json.dumps(g_args)))
        i = obj_end + 1
    return out or None


def _relaxed_allowed_at(content: str, pos: int) -> bool:
    from core.inference.relaxed_json import relaxed_allowed_at  # noqa: PLC0415 -- cycle at import time
    return relaxed_allowed_at(content, pos)


def _relaxed_object_end(content: str, start: int):
    from core.inference.relaxed_json import relaxed_object_end  # noqa: PLC0415 -- cycle at import time
    return relaxed_object_end(content, start)


def _loads_wrapped_call(text: str, *, relaxed: bool = True) -> dict:
    """A wrapped call's JSON object; near-JSON a model sampled (single quotes, a trailing comma, True/None,
    unquoted keys) is read only after strict JSON fails and only when healing is on. Raises ValueError
    when neither reads an object."""
    try:
        return json.loads(text)
    except (json.JSONDecodeError, ValueError):
        if not relaxed:
            raise
        from core.inference.relaxed_json import relaxed_json_object  # noqa: PLC0415 -- failure path only

        obj = relaxed_json_object(text)
        if obj is None:
            raise
        return obj


def parse_tool_calls_from_text(
    content: str,
    *,
    id_offset: int = 0,
    allow_incomplete: bool = True,
    enabled_tool_names = None,
    with_spans: bool = False,
):
    """Rehearsals in think blocks are skipped, not run; the block stays so literal tags in args survive."""
    _think_spans = _think_spans_outside_tool_markup(content)
    _think_starts = [s for s, _e in _think_spans]

    def _in_think(pos: int) -> bool:
        # Spans are ordered and non-overlapping; bisect gives O(log M) per candidate.
        i = bisect.bisect_right(_think_starts, pos) - 1
        return i >= 0 and _think_spans[i][0] <= pos < _think_spans[i][1]

    tool_calls: list[dict] = []
    call_spans: list[tuple] = []
    # A marker inside another call's coverage, even one that failed to parse, is data and is not executed.
    parsed_items = []
    # Mask blocked markerless call bodies here too: passthrough healing reaches this parser unmasked.
    try:
        from core.inference.tool_call_parser import _blocked_markerless_body_spans
        _blocked_spans = _blocked_markerless_body_spans(content, enabled_tool_names)
    except Exception:  # noqa: BLE001 -- no spans just means the old, unmasked behaviour
        _blocked_spans = []

    def _in_blocked(pos: int) -> bool:
        return any(begin <= pos < stop for begin, stop in _blocked_spans)

    markers = [
        mk for mk in _build_markers(content) if not _in_think(mk[0]) and not _in_blocked(mk[0])
    ]
    coverage = _marker_coverage(content, markers)
    covered_until = -1
    relaxed = allow_incomplete
    for idx, (start, brace_end, kind, m) in enumerate(markers):
        covered_by_earlier_marker = start < covered_until
        covered_until = max(covered_until, coverage[idx][1])
        if covered_by_earlier_marker:
            continue
        relaxed_end = None
        if relaxed and kind == "json" and not _relaxed_allowed_at(content, m.end() - 1):
            relaxed = False
        if relaxed and kind == "json":
            # JSON brace matching ends a single-quoted argument at a brace inside it; markers in that
            # argument are data. An object that never closes this way leaves the rest strict.
            relaxed_end = _relaxed_object_end(content, m.end() - 1)
            if relaxed_end is None:
                relaxed = False
            elif relaxed_end != brace_end:
                brace_end = relaxed_end
            else:
                relaxed_end = None
        if brace_end < 0:
            continue
        if not allow_incomplete:
            tail = content[brace_end + 1 :].lstrip()
            close_re = _TC_END_TAG_RE if kind == "json" else _TC_GEMMA_END_TAG_RE
            if close_re.match(tail) is None:
                continue
        try:
            if kind == "json":
                try:
                    obj = _loads_wrapped_call(content[m.end() - 1 : brace_end + 1], relaxed = relaxed)
                except ValueError:
                    if relaxed_end is not None:
                        relaxed = False
                    raise
                if relaxed_end is not None:
                    covered_until = max(covered_until, relaxed_end + 1)
                name = obj.get("name", "")
                # Accept "parameters" (Llama-3.2) and "args" (TML Inkling) as aliases.
                arguments = obj.get("arguments")
                if arguments is None:
                    arguments = obj.get("parameters")
                if arguments is None:
                    arguments = obj.get("args", {})
                if isinstance(arguments, dict):
                    arguments = json.dumps(arguments)
                # Inkling echoes the bare tool NAME before the marker; fold it into the span so it is stripped.
                if name and content.startswith("<|content_invoke_tool_json|>", start):
                    pre = content[:start]
                    if pre.endswith(name):
                        start -= len(name)
                        if content[:start].endswith("<|message_model|>"):
                            start -= len("<|message_model|>")
            else:
                name = m.group(1)
                arguments = json.dumps(_gemma_arguments_to_json(content[m.end() : brace_end]))
        except (json.JSONDecodeError, ValueError):
            continue
        span_end = brace_end + 1
        close_re = _TC_END_TAG_RE if kind == "json" else _TC_GEMMA_END_TAG_RE
        ws = len(content[span_end:]) - len(content[span_end:].lstrip())
        close_m = close_re.match(content, span_end + ws)
        if close_m:
            span_end = close_m.end()
        glued = None
        if (
            allow_incomplete
            and kind == "json"
            and close_m is None
            and name
            and _is_strict_json(content[m.end() - 1 : brace_end + 1])
        ):
            glued = _glued_call_objects(content, span_end, coverage[idx][1])
        if glued:
            # Heal: several call objects glued inside one closed tag; the spans tile up to the close.
            parsed_items.append((start, glued[0][0], name, arguments))
            for g_idx, (g_start, g_name, g_args) in enumerate(glued):
                g_end = glued[g_idx + 1][0] if g_idx + 1 < len(glued) else coverage[idx][1]
                parsed_items.append((g_start, g_end, g_name, g_args))
            continue
        parsed_items.append((start, span_end, name, arguments))

    inside = _OpenParameterIndex(content).inside
    # Coverage is start-sorted: a running max of ends answers each opener by bisect.
    coverage_starts = [s for s, _e in coverage]
    coverage_max_ends = list(itertools.accumulate((e for _s, e in coverage), max))

    def _covered(pos: int) -> bool:
        i = bisect.bisect_right(coverage_starts, pos) - 1
        return i >= 0 and pos < coverage_max_ends[i]

    mention_spans = tag_mention_spans(content) if "<function" in content else []
    func_starts = [
        fm
        for fm in _TC_FUNC_START_RE.finditer(content)
        if not inside(fm.start())
        # `<function=NAME>` alone in backticks names the format; the display keeps it, so it must not run.
        and not in_tag_mention(mention_spans, fm.start())
        and not _in_think(fm.start())
        and not _in_blocked(fm.start())
        and not _covered(fm.start())
    ]
    for idx, fm in enumerate(func_starts):
        func_name = fm.group(1)
        body_start = fm.end()
        next_func = func_starts[idx + 1].start() if idx + 1 < len(func_starts) else len(content)
        # Bounded at the next opener, where body_end is capped anyway.
        end_tag = _TC_END_TAG_RE.search(content, body_start, next_func)
        if end_tag:
            body_end = end_tag.start()
        else:
            body_end = len(content)
        body_end = min(body_end, next_func)
        body = content[body_start:body_end]
        close_idx = _func_close_index(content, body_start, body, inside = inside)
        if close_idx >= 0:
            span_end = body_start + close_idx + len(_FUNC_CLOSE_TAG)
            body = body[:close_idx]
        elif not allow_incomplete:
            continue
        else:
            if body.rstrip().endswith(_FUNC_CLOSE_TAG):
                body = _TC_FUNC_CLOSE_RE.sub("", body)
            span_end = body_end

        arguments: dict = {}
        param_starts = list(_TC_PARAM_START_RE.finditer(body))
        if len(param_starts) == 1:
            pm = param_starts[0]
            val = body[pm.end() :]
            if not allow_incomplete:
                stripped_val = val.rstrip()
                if not stripped_val.endswith(_PARAM_CLOSE_TAG):
                    continue
                val = stripped_val[: -len(_PARAM_CLOSE_TAG)]
            else:
                if val.rstrip().endswith(_PARAM_CLOSE_TAG):
                    val = _TC_PARAM_CLOSE_RE.sub("", val)
            arguments[pm.group(1)] = _trim_param_value(val)
        else:
            valid_params = True
            for pidx, pm in enumerate(param_starts):
                param_name = pm.group(1)
                val_start = pm.end()
                next_param = (
                    param_starts[pidx + 1].start() if pidx + 1 < len(param_starts) else len(body)
                )
                val = body[val_start:next_param]
                if not allow_incomplete:
                    stripped_val = val.rstrip()
                    if not stripped_val.endswith(_PARAM_CLOSE_TAG):
                        valid_params = False
                        break
                    val = stripped_val[: -len(_PARAM_CLOSE_TAG)]
                else:
                    if val.rstrip().endswith(_PARAM_CLOSE_TAG):
                        val = _TC_PARAM_CLOSE_RE.sub("", val)
                arguments[param_name] = _trim_param_value(val)
            if not valid_params:
                continue
        if allow_incomplete and not param_starts:
            arguments = _json_object_body(body) or arguments

        span_start = fm.start()
        ws_start = span_start
        while ws_start > 0 and content[ws_start - 1].isspace():
            ws_start -= 1
        wrap_open = _WRAP_OPEN_RE.search(content, max(0, ws_start - len("<tool_call>")), span_start)
        wrap_close = _WRAP_CLOSE_RE.match(content, span_end)
        if wrap_open and wrap_close:
            span_start = wrap_open.start()
            span_end = wrap_close.end()
        parsed_items.append((span_start, span_end, func_name, json.dumps(arguments)))

    parsed_items.sort(key = lambda item: item[0])
    for start, span_end, name, arguments in parsed_items:
        tool_calls.append(
            {
                "id": f"call_{id_offset + len(tool_calls)}",
                "type": "function",
                "function": {"name": name, "arguments": arguments},
            }
        )
        call_spans.append((start, span_end))

    # One balanced scan in document order, so Mistral calls and rehearsals in one message both parse.
    if not tool_calls:
        for start, end, kind, m in _iter_bracket_spans(
            content, enabled_tool_names = enabled_tool_names
        ):
            if _in_think(start) or _in_blocked(start):
                continue
            # Extend the region over an immediately-following v11 closer so with_spans consumers strip it too.
            closer = re.match(r"\s*\[/TOOL_CALLS\]", content[end:])
            region_end = end + closer.end() if closer else end
            if kind == "array":
                # Decode elements individually: Mistral/Ollama templates emit comma-less multi-call arrays.
                payload, item_ends = _decode_array_items(content, m.end(), end)
                if not payload:
                    continue
                # Tile so every byte belongs to exactly one span and promoted markup is stripped once.
                tile_start = start
                last_span_idx = -1
                for item_idx, item in enumerate(payload):
                    if not isinstance(item, dict) or "name" not in item:
                        continue
                    args = item.get("arguments", {})
                    if isinstance(args, str):
                        # ``arguments`` may itself be a JSON string (OpenAI spec).
                        try:
                            args = json.loads(args)
                        except (json.JSONDecodeError, ValueError):
                            pass
                    if not isinstance(args, (dict, str)):
                        # Non-object scalar becomes {}, not "null", which auto-heal would turn into {"query":"null"}.
                        args = {}
                    tool_calls.append(
                        {
                            "id": f"call_{id_offset + len(tool_calls)}",
                            "type": "function",
                            "function": {
                                "name": item.get("name", ""),
                                # A bare string stays raw; json.dumps would double-encode it.
                                "arguments": args if isinstance(args, str) else json.dumps(args),
                            },
                        }
                    )
                    item_end = item_ends[item_idx] if item_idx < len(item_ends) else region_end
                    last_span_idx = len(call_spans)
                    call_spans.append((tile_start, item_end))
                    tile_start = item_end
                if last_span_idx >= 0:
                    tile_start, _tile_end = call_spans[last_span_idx]
                    call_spans[last_span_idx] = (tile_start, region_end)
            else:
                try:
                    payload = json.loads(content[m.end() : end])
                except (json.JSONDecodeError, ValueError):
                    continue
                if not isinstance(payload, dict):
                    continue
                tool_calls.append(
                    {
                        "id": f"call_{id_offset + len(tool_calls)}",
                        "type": "function",
                        "function": {
                            "name": m.group(1),
                            "arguments": json.dumps(payload),
                        },
                    }
                )
                call_spans.append((start, region_end))

    if with_spans:
        return tool_calls, call_spans
    return tool_calls


def _strip_bracket_tag_calls(text: str, enabled_tool_names = None) -> str:
    """Balanced scan removes nested args whole; enabled_tool_names gates rehearsals (None strips all)."""
    if len(text) > _MAX_BRACKET_SCAN_CHARS:
        return text
    out: list[str] = []
    cursor = 0
    for start, end, _kind, _m in _iter_bracket_spans(text, enabled_tool_names = enabled_tool_names):
        out.append(text[cursor:start])
        cursor = end
    out.append(text[cursor:])
    return "".join(out)


def _tool_call_markup_spans(text: str) -> list[tuple[int, int]]:
    """Includes an unclosed XML call's open-ended span, so its markup does not leak after execution."""
    spans = []
    for pat in _TOOL_CLOSED_PATS:
        required = _PAT_REQUIRED_TOKEN.get(pat)
        scan_end = len(text)
        if isinstance(required, tuple):
            token, opener = required
            first_opener = text.find(opener)
            if first_opener < 0:
                continue
            last_close = text.rfind(token)
            if last_close < 0:
                continue
            scan_end = last_close + len(token)
        elif required is not None and required not in text:
            continue
        spans.extend(m.span() for m in pat.finditer(text, 0, scan_end))
    spans.extend((start, end) for start, end, _kind, _m in _iter_bracket_spans(text))
    if "<minimax:tool_call>" in text:
        # Parameter-aware block bounds, so a quoted closer cannot end the span; lazy, as that module imports this one.
        from core.inference.tool_call_parser import _minimax_block_spans
        spans.extend((start, end) for start, end, _closed in _minimax_block_spans(text))
    # An unclosed opener is a real incomplete call only outside closed/bracket spans.
    for pat in _TOOL_OPEN_XML_TAIL_PATS:
        for m in pat.finditer(text):
            if not any(s <= m.start() < e for s, e in spans):
                spans.append(m.span())
    return spans


def _think_spans_outside_tool_markup(text: str) -> list[tuple[int, int]]:
    """A think tag opening inside a tool-call span is argument data, so it is not a reasoning block."""
    think_spans = (
        [m.span() for m in _THINK_TAG_RE.finditer(text)]
        if "<think>" in text or "[THINK]" in text
        else []
    )
    call_spans = _tool_call_markup_spans(text)
    # Prefilled reasoning: the template opens <think> in the prompt, so a leading span skips calls rehearsed there.
    close = _THINK_CLOSE_RE.search(text) if "</think>" in text or "[/THINK]" in text else None
    if close is not None:
        opener = _THINK_OPEN_RE.search(text)
        if (
            (opener is None or close.start() < opener.start())
            and not any(cs <= close.start() < ce for cs, ce in call_spans)
            and any(cs >= close.end() for cs, ce in call_spans)
        ):
            think_spans = [(0, close.end())] + think_spans
    if not think_spans:
        return think_spans
    if not call_spans:
        return think_spans
    # Merged and bisected: a pairwise scan is quadratic on long output.
    merged: list[list[int]] = []
    for cs, ce in sorted(call_spans):
        if merged and cs <= merged[-1][1]:
            merged[-1][1] = max(merged[-1][1], ce)
        else:
            merged.append([cs, ce])
    starts = [cs for cs, _ in merged]
    kept = []
    for s, e in think_spans:
        i = bisect.bisect_right(starts, s) - 1
        if i < 0 or s >= merged[i][1]:
            kept.append((s, e))
    return kept


def strip_outside_think(text: str, strip_segment) -> str:
    """Applies strip_segment outside think blocks; is_last is True only after the final block."""
    think_spans = _think_spans_outside_tool_markup(text)
    if not think_spans:
        return strip_segment(text, True)
    pieces: list[str] = []
    prev = 0
    for s, e in think_spans:
        pieces.append(strip_segment(text[prev:s], False))
        pieces.append(text[s:e])
        prev = e
    pieces.append(strip_segment(text[prev:], True))
    return "".join(pieces)


def _strip_gemma_native_spans(text: str, *, final: bool) -> str:
    """Strips complete Gemma-native spans, brace/quote-balanced so an in-argument close tag cannot
    truncate one; an incomplete span is dropped to EOF when final, else kept."""
    out: list[str] = []
    cursor = 0
    for match in _TC_GEMMA_START_RE.finditer(text):
        start = match.start()
        if start < cursor:
            continue
        brace_end = _balanced_brace_end(text, match.end() - 1, gemma_quotes = True)
        if brace_end is None:
            # Unbalanced: nothing completes from here on, so stop either way (rescanning would be quadratic).
            if final:
                out.append(text[cursor:start])
                cursor = len(text)
            break
        # Junk between } and the close tag is malformed markup: strip through the close, or stop if none.
        close = _TC_GEMMA_END_TAG_RE.search(text, brace_end + 1)
        if close is None:
            if final:
                out.append(text[cursor:start])
                cursor = len(text)
            break
        out.append(text[cursor:start])
        cursor = close.end()
    out.append(text[cursor:])
    return "".join(out)


def _gemma_span_ranges(text: str) -> list:
    """(start, end) per complete Gemma-native span, same walk as the strip, without stripping."""
    ranges: list[tuple] = []
    cursor = 0
    for match in _TC_GEMMA_START_RE.finditer(text):
        start = match.start()
        if start < cursor:
            continue
        brace_end = _balanced_brace_end(text, match.end() - 1, gemma_quotes = True)
        if brace_end is None:
            break
        close = _TC_GEMMA_END_TAG_RE.search(text, brace_end + 1)
        if close is None:
            break
        ranges.append((start, close.end()))
        cursor = close.end()
    return ranges


def _strip_closed_blocks_outside_gemma(text: str) -> str:
    """Skips matches starting inside a Gemma span: deleting across its boundary mangles the close."""
    ranges = _gemma_span_ranges(text)
    if not ranges:
        return strip_tool_patterns(text, _TOOL_CLOSED_BLOCK_PATS)
    for pat in _TOOL_CLOSED_BLOCK_PATS:
        required = _PAT_REQUIRED_TOKEN.get(pat)
        scan_end = len(text)
        if isinstance(required, tuple):
            token, opener = required
            first_opener = text.find(opener)
            if first_opener < 0:
                continue
            last_close = text.rfind(token)
            if last_close < 0:
                continue
            scan_end = last_close + len(token)
        elif required is not None and required not in text:
            continue
        out: list[str] = []
        pos = 0
        while True:
            m = pat.search(text, pos, scan_end)
            if m is None:
                out.append(text[pos:])
                break
            covering = next((r for r in ranges if r[0] <= m.start() < r[1]), None)
            if covering is not None:
                out.append(text[pos : covering[1]])
                pos = covering[1]
                continue
            out.append(text[pos : m.start()])
            pos = m.end()
        new_text = "".join(out)
        if new_text != text:
            text = new_text
            ranges = _gemma_span_ranges(text)
    return text


def _strip_markup_segment(
    text: str,
    *,
    final: bool,
    enabled_tool_names = None,
) -> str:
    # Order matters: bracket-tag scan, then quote-aware Gemma passes, then the regex sweeps.
    text = _strip_bracket_tag_calls(text, enabled_tool_names = enabled_tool_names)
    text = _strip_closed_blocks_outside_gemma(text)
    text = _strip_gemma_native_spans(text, final = final)
    patterns = _TOOL_ALL_PATS if final else _TOOL_CLOSED_PATS
    return apply_tool_strip_patterns(text, patterns, enabled_tool_names = enabled_tool_names)


def strip_tool_call_markup(
    text: str,
    *,
    final: bool = False,
    enabled_tool_names = None,
) -> str:
    """final=True also strips trailing incomplete blocks and whitespace; think blocks kept verbatim."""
    result = strip_outside_think(
        text,
        lambda seg, is_last: _strip_markup_segment(
            seg, final = final and is_last, enabled_tool_names = enabled_tool_names
        ),
    )
    return result.strip() if final else result