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.

59.0 KB
Raw Blame
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0

"""Dependency-light per-response ledger for GGUF and safetensors loops; execution lives in backends."""

from __future__ import annotations

import ast
import copy
import json
import math
import re
from dataclasses import dataclass, field
from typing import Any, Collection, Literal, Mapping, Sequence
from urllib.parse import urlparse

from core.inference.browser_agent import BROWSER_TOOL_NAMES
from core.inference.llama_tool_schema import unrelaxed
from core.inference.mcp_images import is_image_tool, split_images as split_mcp_images
from core.inference.media_chat_tools import MEDIA_CHAT_TOOLS
from core.inference.tool_facts import REPEATABLE, awaits_user, reads_only, repeatable

# Provenance the envelope is trusted on; stamped by mcp_client.
MCP_TOOL_PREFIX = "mcp__"
# tools.MCP_TOOL_SEARCH_NAME; tools imports this module.
MCP_TOOL_SEARCH_NAME = "mcp_tool_search"
from core.inference.tool_call_parser import TOOL_ERROR_NUDGE, TOOL_ERROR_PREFIXES

# Never deduplicated: an identical call is new work (the page as it is now, another render).
REPEATABLE_TOOL_NAMES = REPEATABLE


_CANONICAL_HEAL_ARG = {
    "python": "code",
    "terminal": "command",
    "render_html": "code",
    # web_search declares no required argument (a `url`-only call fetches), but a bare string is a query.
    "web_search": "query",
}

# Read by `execute_tool` to report the real problem instead of a missing key.
UNPARSED_ARGUMENTS_KEY = "__unsloth_unparsed_arguments__"


# Anything that ends a JSON token. A tail free of all of them never finished arriving.
_JSON_STRUCTURAL = frozenset(',:{}[]" \t\n\r')


def _reject_json_constant(name: str) -> Any:
    """Refuse ``NaN`` / ``Infinity``: ``json.loads`` takes them, ``JSON.parse`` does not."""
    raise ValueError(f"{name} is not JSON")


# Built once: `json.loads` with any keyword constructs a fresh decoder per call.
_STRICT_JSON_DECODER = json.JSONDecoder(parse_constant = _reject_json_constant)


def _looks_like_broken_json(raw: str) -> bool:
    """A cut-off call runs out of input; text that merely starts with a brace fails with input left."""
    text = raw.strip()
    if not text.startswith(("{", "[")):
        return False
    try:
        _STRICT_JSON_DECODER.decode(text)
    except json.JSONDecodeError as error:
        if error.msg.startswith("Unterminated string") or error.pos >= len(text):
            return True
        # A token cut mid-way reports at its start, so check that the rest is one unfinished token.
        # A bad property name is malformed, not truncated, and stays healable.
        if error.msg.startswith("Expecting property name"):
            return False
        # A complete document with trailing junk lost nothing.
        if error.msg.startswith("Extra data"):
            return False
        remainder = text[error.pos :]
        return bool(remainder) and not any(ch in _JSON_STRUCTURAL for ch in remainder)
    except (ValueError, RecursionError):
        # Digit cap, recursion limit or NaN/Infinity: unreadable is as broken as cut off.
        return True
    return False


def _single_string_argument(function: Mapping) -> "str | None":
    """That function's one required string argument, or None when it has anything else."""
    parameters = function.get("parameters")
    if not isinstance(parameters, Mapping):
        return None
    properties = parameters.get("properties")
    required = parameters.get("required")
    if not isinstance(properties, Mapping) or not isinstance(required, list):
        return None
    required_names = [item for item in required if isinstance(item, str)]
    if len(required_names) != 1:
        return None
    key = required_names[0]
    schema = properties.get(key)
    if not isinstance(schema, Mapping):
        return None
    kind = schema.get("type")
    if kind == "string" or (isinstance(kind, list) and "string" in kind):
        return key
    return None


def _healable_keys_from_schemas() -> "dict[str, str]":
    """Derived from the schemas, so a new tool cannot silently go stale in a hand-kept map."""
    try:
        from core.inference.tools import ALL_TOOLS  # noqa: PLC0415 -- cycle at import time
    except Exception:  # noqa: BLE001 -- healing must never break a chat
        return {}
    return _healable_keys_from(ALL_TOOLS)


def _healable_keys_from(tools) -> "dict[str, str]":
    keys: dict[str, str] = {}
    for tool in tools or []:
        function = tool.get("function") if isinstance(tool, Mapping) else None
        if not isinstance(function, Mapping):
            continue
        name = str(function.get("name") or "")
        if not name:
            continue
        key = _single_string_argument(function)
        if key is not None:
            keys[name] = key
    return keys


_HEAL_ARG_CACHE: "dict[str, str] | None" = None


def _heal_arg_key(tool_name: str, tool_schemas = None) -> "str | None":
    """MCP tools are absent from ALL_TOOLS, so the request's tool_schemas must also be read."""
    global _HEAL_ARG_CACHE
    if tool_name in _CANONICAL_HEAL_ARG:
        return _CANONICAL_HEAL_ARG[tool_name]
    if _HEAL_ARG_CACHE is None:
        _HEAL_ARG_CACHE = _healable_keys_from_schemas()
    key = _HEAL_ARG_CACHE.get(tool_name)
    if key is not None or not tool_schemas:
        return key
    # Not cached: one chat's MCP tools must not decide another chat's healing.
    return _healable_keys_from(tool_schemas).get(tool_name)


def _unreadable_arguments_summary(fragment: str) -> dict[str, str]:
    """Must stay parseable JSON: a replayed arguments field that does not parse fails the whole request."""
    return {
        "error": (f"arguments were cut off after {len(fragment)} characters and could not be read")
    }


TRUNCATED_TOOL_TURN_MESSAGE = (
    "The model stopped before completing its tool calls. These tool calls were not run. "
    "Retry with smaller changes or more room for the response."
)


_ONE_SHOT_TOOLS = frozenset({"render_html"})

NoopReason = Literal["duplicate", "disabled", "forced_mismatch", "render_html_repeat"]
ToolAction = Literal["execute", "duplicate", "disabled", "forced_mismatch", "render_html_repeat"]


@dataclass(frozen = True)
class CoercedArguments:
    """Normalized tool arguments plus whether healing changed the shape."""

    arguments: dict[str, Any]
    healed: bool = False


def canonical_arguments_text(arguments: Any) -> str:
    """Not sorted on purpose: the replay must match the token sequence already in the prompt cache."""
    return json.dumps(arguments, ensure_ascii = False, sort_keys = False, separators = (",", ":"))


@dataclass(frozen = True)
class ToolCallDecision:
    """Decision made before any visible tool event is emitted."""

    action: ToolAction
    tool_name: str
    arguments: dict[str, Any]
    tool_call_id: str = ""
    # For an id-less call this is the client-minted spelling, not the replayed id.
    card_call_id: str = ""
    key: str = ""
    provenance: dict[str, Any] = field(default_factory = dict)
    status_text: str = ""
    noop_result: str = ""

    @property
    def should_execute(self) -> bool:
        return self.action == "execute"

    @property
    def card_id(self) -> str:
        """The id every frontend-visible event for this call is addressed to."""
        return self.card_call_id or self.tool_call_id

    @property
    def emit_visible_events(self) -> bool:
        """Only real executions should become frontend-visible tool cards."""
        return self.should_execute

    @property
    def noop_reason(self) -> NoopReason | None:
        if self.action == "execute":
            return None
        return self.action

    @property
    def unparsed_fragment(self) -> "str | None":
        """Internal UNPARSED_ARGUMENTS_KEY must not leak to the card or replay, so both boundaries
        use this."""
        if isinstance(self.arguments, Mapping) and UNPARSED_ARGUMENTS_KEY in self.arguments:
            return str(self.arguments.get(UNPARSED_ARGUMENTS_KEY) or "")
        return None

    def tool_start_payload(self) -> dict[str, Any]:
        fragment = self.unparsed_fragment
        # Use `raw` for unparsed arguments so the card shows the model's own text, not an internal sentinel.
        arguments = {"raw": fragment} if fragment is not None else self.arguments
        return {
            "tool_name": self.tool_name,
            "tool_call_id": self.card_id,
            "arguments": arguments,
            # Re-encoding `arguments` in the browser would round ids past 2**53 (JSON.parse).
            "arguments_text": canonical_arguments_text(arguments),
            "provenance": self.provenance,
        }

    def tool_start_event(self) -> dict[str, Any]:
        return {"type": "tool_start", **self.tool_start_payload()}

    def tool_approved_event(self, approval_id: str) -> dict[str, Any]:
        """Tells the run's other followers the parked call was allowed, ahead of tool_end."""
        return {
            "type": "tool_approved",
            "tool_name": self.tool_name,
            "tool_call_id": self.card_id,
            "approval_id": approval_id,
        }

    def as_assistant_tool_call(self) -> dict[str, Any]:
        """Return an OpenAI-style tool_call with normalized arguments."""
        fragment = self.unparsed_fragment
        tool_call: dict[str, Any] = {
            "type": "function",
            "function": {
                "name": self.tool_name,
                # Must parse as JSON: llama-server 500s while rendering the template otherwise.
                "arguments": json.dumps(_unreadable_arguments_summary(fragment))
                if fragment is not None
                else canonical_arguments_text(self.arguments),
            },
        }
        if self.tool_call_id:
            tool_call["id"] = self.tool_call_id
        return tool_call


@dataclass(frozen = True)
class ToolCallCompletion:
    """Result/nudge that should be fed back to the next model turn."""

    decision: ToolCallDecision
    result: str
    is_error: bool = False
    executed: bool = False

    def tool_end_payload(self) -> dict[str, Any]:
        # Mask here too, not only in model_message: the frontend persists this payload and replays it.
        result = self.result
        return {
            "tool_name": self.decision.tool_name,
            "tool_call_id": self.decision.card_id,
            "result": redact_studio_credentials(result) if isinstance(result, str) else result,
            "provenance": self.decision.provenance,
        }

    def tool_end_event(self) -> dict[str, Any]:
        return {"type": "tool_end", **self.tool_end_payload()}

    def tool_message(self) -> dict[str, Any]:
        """Return the OpenAI-compatible tool message for a real execution."""
        if not self.executed:
            raise ValueError("No-op completions are internal nudges, not tool messages")
        return self.model_message()

    def model_message(self) -> dict[str, Any]:
        """No-op decisions are not tool output, so they return as a hidden user nudge, not role=tool."""
        if not self.executed:
            return {"role": "user", "content": self.result}

        content = strip_result_for_model(self.result, self.decision.tool_name)
        if self.is_error:
            content = content + TOOL_ERROR_NUDGE
        message: dict[str, Any] = {
            "role": "tool",
            "name": self.decision.tool_name,
            "content": content,
        }
        if self.decision.tool_call_id:
            message["tool_call_id"] = self.decision.tool_call_id
        return message

    def mcp_images(self) -> list[dict]:
        """Only MCP and image-viewer tools yield images; a plain suffix elsewhere would attach bytes."""
        if not self.executed or not is_image_tool(self.decision.tool_name):
            return []
        return split_mcp_images(self.result)[1]


@dataclass(frozen = True)
class _ToolCallRecord:
    key: str
    is_error: bool
    executed: bool
    action: ToolAction


def _json_default(value: Any) -> str:
    return str(value)


def canonical_tool_call_key(tool_name: str, arguments: Mapping[str, Any]) -> str:
    """Return a stable key for duplicate detection."""
    canonical_args = json.dumps(
        dict(arguments),
        ensure_ascii = False,
        sort_keys = True,
        separators = (",", ":"),
        default = _json_default,
    )
    return f"{tool_name}:{canonical_args}"


# "0"/"1" are left out: a native `0` arrives already typed, so they would mean two things
_SCHEMA_TRUE_WORDS = frozenset({"true", "yes"})
_SCHEMA_FALSE_WORDS = frozenset({"false", "no"})
# not ValueErrors, so a decode-shaped except would let deep model output escape as a 500
_DECODE_ERRORS = (ValueError, RecursionError)
_LITERAL_ERRORS = (*_DECODE_ERRORS, SyntaxError, MemoryError)


# Group 1 is the closing quote. The `\?$` tail stops a started match failing, which would make
# `finditer` rescan every later quote.
_JSON_STRING_RE = re.compile(r'"(?:[^"\\]|\\.)*(?:(")|\\?$)', re.S)
_JSON_CLOSER = {"[": "]", "{": "}"}


def _balanced(segment: str, opened: "list[str]") -> str:
    kept: list[str] = []
    for ch in segment:
        if ch in _JSON_CLOSER:
            opened.append(_JSON_CLOSER[ch])
            kept.append(ch)
        elif ch in "]}":
            # the commonest slip: a closer of the wrong kind becomes the right one
            if opened:
                kept.append(opened.pop())
        else:
            kept.append(ch)
    return "".join(kept)


def _repair_json_value(text: str) -> Any:
    """Parse near-valid JSON whose brackets do not balance, or None if it still will not."""
    parts: list[str] = []
    opened: list[str] = []
    cursor = 0
    open_string = ""
    for match in _JSON_STRING_RE.finditer(text):
        parts += [_balanced(text[cursor : match.start()], opened), match.group()]
        open_string = "" if match.group(1) else '"'
        cursor = match.end()
    parts += [_balanced(text[cursor:], opened), open_string, *reversed(opened)]
    try:
        return json.loads("".join(parts), strict = False)
    except _DECODE_ERRORS:
        return None


# Followed to find a declaration; `nullable` is OpenAPI 3.0's spelling of a type union.
_READ_KEYWORDS = frozenset(
    {
        "type",
        "nullable",
        "properties",
        "items",
        "prefixItems",
        "additionalItems",
        "additionalProperties",
    }
)
# cannot move a declaration out of reach: annotations, and constraints that only reject
_INERT_KEYWORDS = frozenset(
    {
        "title",
        "description",
        "default",
        "examples",
        "example",
        "deprecated",
        "readOnly",
        "writeOnly",
        "format",
        "$comment",
        "$schema",
        "$id",
        "$anchor",
        "$defs",
        "definitions",
        "enum",
        "const",
        "required",
        "dependentRequired",
        "minimum",
        "maximum",
        "exclusiveMinimum",
        "exclusiveMaximum",
        "multipleOf",
        "minLength",
        "maxLength",
        "pattern",
        "minItems",
        "maxItems",
        "uniqueItems",
        "minContains",
        "maxContains",
        "minProperties",
        "maxProperties",
    }
)
_UNION_KEYWORDS = frozenset({"anyOf", "oneOf"})
# Matched exactly: an unknown type name is as unreadable as an unknown keyword.
_JSON_SCHEMA_TYPES = frozenset(
    {
        "array",
        "boolean",
        "integer",
        "null",
        "number",
        "object",
        "string",
    }
)
_KNOWN_KEYWORDS = _READ_KEYWORDS | _INERT_KEYWORDS | _UNION_KEYWORDS


def _readable(spec: Any) -> bool:
    """Allowlist: composition, references or newer drafts can move declarations out of reach."""
    return isinstance(spec, Mapping) and spec.keys() <= _KNOWN_KEYWORDS


def _read_schema(spec: Any) -> "tuple[Any, str | None, bool]":
    """A union reads only if every branch names a type; else an integer branch would turn "001" into 1."""
    spec = unrelaxed(spec)
    if not _readable(spec):
        return None, None, False
    union = _UNION_KEYWORDS & spec.keys()
    if union and (len(union) > 1 or not _READ_KEYWORDS.isdisjoint(spec)):
        return None, None, False
    kind = spec.get("type")
    chosen = spec
    if isinstance(kind, str):
        named = [kind]
    elif isinstance(kind, list):
        named = list(kind)
    elif union:
        branches = spec.get("anyOf") or spec.get("oneOf")
        if not isinstance(branches, list) or not branches:
            return None, None, False
        named = []
        for branch in branches:
            branch = unrelaxed(branch)
            name = branch.get("type") if _readable(branch) else None
            if not isinstance(name, str) or _UNION_KEYWORDS & branch.keys():
                return None, None, False
            named.append(name)
            if named[-1] != "null":
                chosen = branch
    elif kind is None:
        return spec, None, False
    else:
        return None, None, False
    if not named or not all(isinstance(name, str) and name in _JSON_SCHEMA_TYPES for name in named):
        return None, None, False
    if chosen.get("nullable") is True:
        named.append("null")
    rest = [k for k in named if k != "null"]
    if len(rest) > 1 or (not rest and "null" not in named):
        return None, None, False
    return chosen, rest[0] if rest else None, "null" in named


# A schema is model-facing data, so its nesting is not trusted to be shallow.
_MAX_SCHEMA_DEPTH = 8


def _coerce_declared_value(text: str, declared: str, repair: bool) -> Any:
    stripped = text.strip()
    if declared == "boolean":
        lowered = stripped.lower()
        if lowered in _SCHEMA_TRUE_WORDS:
            return True
        if lowered in _SCHEMA_FALSE_WORDS:
            return False
    elif declared in ("integer", "number"):
        try:
            # float() would round 9007199254740993, which an already-numeric argument keeps.
            return int(stripped)
        except ValueError:
            pass
        try:
            number = float(stripped)
        except (ValueError, OverflowError):
            return text
        # "nan"/"inf" parse, but json.dumps writes them bare and the client rejects that.
        if math.isfinite(number) and (declared == "number" or number.is_integer()):
            return number
    elif declared == "array":
        return _coerce_container(text, list, repair)
    elif declared == "object":
        return _coerce_container(text, dict, repair)
    return text


def _usable_container(value: Any, want: type) -> bool:
    """A ``want`` that survives the JSON re-encoding of ``arguments``: both decoders admit
    what ``json.dumps`` will not write back, such as an integer key returning as a STRING."""
    if not isinstance(value, want):
        return False
    try:
        dumped = json.dumps(value, allow_nan = False, sort_keys = True, ensure_ascii = False)
        dumped.encode("utf-8")  # a lone surrogate survives dumps and dies encoding the reply
        return json.loads(dumped) == value
    except (TypeError, ValueError, RecursionError):
        return False


def _coerce_container(text: str, want: type, repair: bool) -> Any:
    """``text`` read as the DECLARED container, tolerating a Python literal and, when
    ``repair``, unbalanced brackets. Rewriting brackets is what auto-heal opts out of."""
    try:
        parsed = json.loads(text, strict = False)
    except _DECODE_ERRORS:
        parsed = None
    if _usable_container(parsed, want):
        return parsed
    try:
        literal = ast.literal_eval(text)
    except _LITERAL_ERRORS:
        literal = None
    if isinstance(literal, tuple):
        literal = list(literal)
    if _usable_container(literal, want):
        return literal
    repaired = _repair_json_value(text) if repair else None
    return repaired if _usable_container(repaired, want) else text


def _coerce_by_property(value: Any, spec: Any, depth: int, repair: bool) -> Any:
    if depth >= _MAX_SCHEMA_DEPTH:
        return value
    spec, declared, nullable = _read_schema(spec)
    if spec is None:
        return value
    if isinstance(value, str):
        if declared == "string":
            return value
        if nullable and value.strip().lower() == "null":
            return None
        if declared is None:
            return value
        value = _coerce_declared_value(value, declared, repair)
    # Descend only with the same declaration the conversion needs, or the syntaxes disagree.
    if declared == "object" and isinstance(value, Mapping):
        nested = spec.get("properties")
        nested = nested if isinstance(nested, Mapping) else {}
        extra = spec.get("additionalProperties")
        extra = extra if isinstance(extra, Mapping) else None
        if nested or extra:
            return {
                k: _coerce_by_property(v, nested.get(k, extra), depth + 1, repair)
                for k, v in value.items()
            }
    elif declared == "array" and isinstance(value, list):
        items = spec.get("items")
        prefix = items if isinstance(items, list) else spec.get("prefixItems")
        if isinstance(prefix, list):
            # A schema per position: draft-07 tuple `items`, 2020-12 `prefixItems`.
            rest = spec.get("additionalItems") if isinstance(items, list) else items
            return [
                _coerce_by_property(v, prefix[i] if i < len(prefix) else rest, depth + 1, repair)
                for i, v in enumerate(value)
            ]
        if isinstance(items, Mapping):
            return [_coerce_by_property(v, items, depth + 1, repair) for v in value]
    return value


def coerce_arguments_by_schema(
    arguments: Mapping[str, Any],
    properties: Any,
    *,
    repair: bool = False,
) -> dict:
    """XML values arrive as raw text, so "false" is read per the schema; bool("false") is True."""
    if not isinstance(properties, Mapping) or not properties:
        return dict(arguments)
    return {k: _coerce_by_property(v, properties.get(k), 0, repair) for k, v in arguments.items()}


def _declared_properties(tool_name: str, tool_schemas) -> Any:
    for tool in tool_schemas or []:
        function = tool.get("function") if isinstance(tool, Mapping) else None
        if not isinstance(function, Mapping) or function.get("name") != tool_name:
            continue
        parameters = function.get("parameters")
        return parameters.get("properties") if isinstance(parameters, Mapping) else None
    return None


def _mcp_tool_spec(tool_name: str) -> Any:
    try:
        from core.inference.tools import mcp_tool_spec  # noqa: PLC0415 -- cycle at import time
        from core.inference.chat_template_helpers import neutralize_tool_descriptions  # noqa: PLC0415

        specs = neutralize_tool_descriptions([mcp_tool_spec(tool_name)])
        return specs[0] if specs else None
    except Exception:  # noqa: BLE001 -- an unknown tool stays disabled
        return None


def _mcp_tool_search_specs(result: str) -> list:
    specs = []
    # The worker's result budget is absent here; its returned schemas are authoritative.
    for line in result.splitlines():
        if not line.startswith("  schema: "):
            continue
        try:
            schema = json.loads(line.removeprefix("  schema: "))
        except (ValueError, TypeError):
            continue
        name = _tool_name_from_schema(schema) if isinstance(schema, Mapping) else None
        spec = _mcp_tool_spec(name) if name else None
        if spec is not None:
            specs.append(spec)
    return specs


def _tool_name_key(name: str) -> str:
    return name.lower().replace("-", "_")


def _canonical_tool_name(name: str, allowed: Collection[str]) -> "str | None":
    """The one enabled tool a sampled name means when only its case or ``-``/``_`` differ (WEB_SEARCH,
    web-search). Never an execution-class or MCP tool: those run only under their exact name, so a bare
    call cannot reach them by a near spelling. None when no tool, or more than one, matches."""
    # ASCII only: Unicode case folding maps other letters onto ASCII ones (``ſ`` -> ``s``, Kelvin sign -> ``k``).
    if not name or not name.isascii():
        return None
    key = _tool_name_key(name)
    matches = [tool for tool in allowed if _tool_name_key(tool) == key]
    if len(matches) != 1:
        return None
    match = matches[0]
    if match in _tool_healing_exec_names() or match.startswith(MCP_TOOL_PREFIX):
        return None
    return match


def _tool_healing_exec_names() -> "frozenset[str]":
    from core.tool_healing import EXECUTION_CLASS_TOOL_NAMES  # noqa: PLC0415 -- cycle at import time
    return EXECUTION_CLASS_TOOL_NAMES


def _relaxed_arguments(raw_args: str, properties: Any) -> "dict | None":
    """The object near-JSON arguments spell, kept only when it names a declared argument."""
    from core.inference.relaxed_json import relaxed_json_object  # noqa: PLC0415 -- failure path only

    repaired = relaxed_json_object(raw_args)
    if not repaired:
        return None
    if (
        isinstance(properties, Mapping)
        and properties
        and not any(k in properties for k in repaired)
    ):
        return None
    return repaired


def coerce_tool_arguments(
    raw_args: Any,
    *,
    heal: bool,
    tool_name: str = "",
    tool_schemas = None,
) -> CoercedArguments:
    """Schema typing is not gated on heal: healing invents structure, the schema is the tool's contract."""
    properties = _declared_properties(tool_name, tool_schemas) if tool_name else None
    if isinstance(raw_args, Mapping):
        return CoercedArguments(
            coerce_arguments_by_schema(raw_args, properties, repair = heal), False
        )
    if isinstance(raw_args, str):
        try:
            # NaN/Infinity would replay as JSON no provider parses.
            parsed = _STRICT_JSON_DECODER.decode(raw_args)
            if isinstance(parsed, Mapping):
                return CoercedArguments(
                    coerce_arguments_by_schema(parsed, properties, repair = heal), False
                )
        except (ValueError, RecursionError):
            # Must not raise: this runs before the budget gate, so a raise aborts the whole turn.
            pass
        if heal:
            # Near-JSON (single quotes, a trailing comma, True/None, an object encoded as a string) is the
            # object it spells; wrapping it whole would run the tool on the call's own source text.
            repaired = _relaxed_arguments(raw_args, properties)
            if repaired is not None:
                return CoercedArguments(
                    coerce_arguments_by_schema(repaired, properties, repair = heal), True
                )
            # Text that opens like JSON but fails to parse is a truncated object, not a bare string;
            # wrapping it whole would pass the fragment as the argument value.
            key = (
                None
                if _looks_like_broken_json(raw_args)
                else _heal_arg_key(tool_name, tool_schemas)
            )
            if key is not None:
                return CoercedArguments({key: raw_args}, True)
            # No single argument fits; do not invent one, since an invented key gets blamed on the model as a type error.
            return CoercedArguments({UNPARSED_ARGUMENTS_KEY: raw_args}, False)
        return CoercedArguments({"raw": raw_args}, False)
    return CoercedArguments({}, False)


def tool_event_provenance(**flags: object) -> dict[str, object]:
    """Return provenance metadata with falsey flags omitted."""
    provenance: dict[str, object] = {"source": "local"}
    for key, value in flags.items():
        if value is not None and value is not False:
            provenance[key] = value
    return provenance


def mcp_display_parts(tool_name: str) -> "tuple[str, str] | None":
    """(server display name, bare tool name) for a resolvable mcp__ tool."""
    if not tool_name.startswith("mcp__"):
        return None
    parts = tool_name.split("__", 2)
    if len(parts) < 3 or not parts[1] or not parts[2]:
        return None
    try:
        from core.inference.tools import _mcp_raw_tool_name
        from storage import mcp_servers_db

        server = mcp_servers_db.get_server_for_tool(parts[1])
        display = (server or {}).get("display_name")
        return (str(display), _mcp_raw_tool_name(tool_name)) if display else None
    except Exception:  # noqa: BLE001
        return None


def provisional_tool_provenance(tool_name: str) -> dict[str, object]:
    """Provisional card provenance with MCP name; an early or orphaned card never shows the id."""
    mcp = mcp_display_parts(tool_name)
    return tool_event_provenance(
        provisional = True,
        mcp_server = mcp[0] if mcp else None,
        mcp_tool = mcp[1] if mcp else None,
    )


def status_for_tool(tool_name: str, arguments: Mapping[str, Any]) -> str:
    """Return the status text already used by local tool streams."""
    if tool_name == "web_search":
        url = str(arguments.get("url") or "").strip()
        if url:
            # Bare hosts are fetched as https, so normalize first.
            from core.inference.tools import _normalize_url_scheme

            try:
                parsed = urlparse(_normalize_url_scheme(url))
            except ValueError:
                # Outside the fetch's exception handler: raising here kills the turn.
                return "Reading page..."
            if parsed.scheme in ("http", "https") and parsed.hostname:
                host = parsed.hostname
                if host.startswith("www."):
                    host = host[4:]
                return f"Reading: {host}"
            return "Reading page..."
        image_queries = arguments.get("image_queries")
        images = (
            ", ".join(str(q) for q in image_queries[:5])
            if isinstance(image_queries, list) and image_queries
            else ""
        )
        query = str(arguments.get("query") or "").strip()
        if images and not query:
            return f"Finding images: {images}"
        if images:
            return f"Searching: {query} (images: {images})"
        return f"Searching: {arguments.get('query', '')}"
    if tool_name == "python":
        preview = str(arguments.get("code") or "").strip().split("\n")[0][:60]
        return f"Running Python: {preview}" if preview else "Running Python..."
    if tool_name == "terminal":
        preview = str(arguments.get("command") or "")[:60]
        return f"Running: {preview}" if preview else "Running command..."
    if tool_name == "view_image":
        return "Viewing image: " + str(arguments.get("path") or "")[:80]
    if tool_name in MEDIA_CHAT_TOOLS:
        kind = "image" if tool_name == "generate_image" else "video"
        return f"Generating {kind}: " + str(arguments.get("prompt") or "")[:60]
    if tool_name == "edit_file":
        # The name, not the patch: the tool card below already shows the edit.
        path = str(arguments.get("path") or "").strip()
        name = path.replace("\\", "/").rstrip("/").rpartition("/")[2]
        return f"Editing: {name}" if name else "Editing file..."
    if tool_name in BROWSER_TOOL_NAMES:
        return _browser_status(tool_name, arguments)
    mcp = mcp_display_parts(tool_name)
    if mcp:
        return f"Calling: {mcp[0]} · {mcp[1]}"
    return f"Calling: {tool_name}"


def _browser_status(tool_name: str, arguments: Mapping[str, Any]) -> str:
    """The badge for a browser tool: what it does, in the user's terms, not the tool's name."""

    def text(key: str, limit: int = 60) -> str:
        return " ".join(str(arguments.get(key) or "").split())[:limit]

    ref = text("ref", 12)
    if tool_name == "browser_navigate":
        url = text("url", 4096)
        if url.lower() in ("back", "forward", "reload"):
            return {
                "back": "Going back",
                "forward": "Going forward",
                "reload": "Reloading the page",
            }[url.lower()]
        try:
            host = urlparse(url if "://" in url else f"https://{url}").hostname or ""
        except ValueError:
            host = ""
        host = host[4:] if host.startswith("www.") else host
        return f"Opening: {host}" if host else "Opening a page..."
    if tool_name == "browser_snapshot":
        return "Reading the page"
    if tool_name == "browser_find":
        query = text("query")
        return f"Finding: {query}" if query else "Finding on the page..."
    if tool_name == "browser_click":
        return f"Clicking: {ref}" if ref else "Clicking the page"
    if tool_name == "browser_type":
        preview = text("text", 40)
        return f"Typing: {preview}" if preview else "Typing..."
    if tool_name == "browser_select":
        value = text("value", 40)
        return f"Choosing: {value}" if value else "Choosing an option..."
    if tool_name == "browser_scroll":
        return "Scrolling up" if text("direction").lower() == "up" else "Scrolling down"
    if tool_name == "browser_press_key":
        key = text("key", 20)
        return f"Pressing: {key}" if key else "Pressing a key..."
    if tool_name == "browser_evaluate":
        return "Running a script on the page"
    if tool_name == "browser_screenshot":
        return "Taking a screenshot"
    if tool_name == "browser_history":
        query = text("query")
        return f"Searching browsing history: {query}" if query else "Reading browsing history"
    if tool_name == "browser_move_mouse":
        return "Moving the mouse"
    if tool_name == "browser_drag":
        return "Dragging"
    if tool_name == "browser_tabs":
        return "Switching tabs" if text("tab") else "Listing browser tabs"
    if tool_name == "browser_read_file":
        return "Reading the file"
    if tool_name == "browser_edit_file":
        return "Editing the file"
    return f"Calling: {tool_name}"


def awaiting_approval_status(tool_name: str) -> str:
    """Not started yet, so a Running status with a climbing timer would read as a hang."""
    if tool_name == "python":
        return "Waiting for approval: Python"
    if tool_name == "terminal":
        return "Waiting for approval: command"
    if tool_name == "edit_file":
        return "Waiting for approval: file edit"
    mcp = mcp_display_parts(tool_name)
    if mcp:
        return f"Waiting for approval: {mcp[0]} · {mcp[1]}"
    return f"Waiting for approval: {tool_name}"


def is_tool_error(result: str) -> bool:
    return isinstance(result, str) and result.lstrip().startswith(TOOL_ERROR_PREFIXES)


TOOL_MODEL_SUFFIX_KEY = "studio_model_suffix"


def with_appended_text(content, text: str):
    """``content`` with ``text`` at the end. A part list (an image a tool returned may have joined
    the turn) gets a text part; formatting it as a string ships the image as base64 prose."""
    if isinstance(content, list):
        return [*content, {"type": "text", "text": text}]
    return f"{content}{text}"


def restore_replayed_tool_results(messages: Sequence[Any]) -> list[Any]:
    """Replayed tool results as the model saw them (error nudge, folded feedback from
    ``extra_content``, no citation map), so the cached prefix holds. Idempotent."""
    out = list(messages)
    for i, message in enumerate(out):
        if not isinstance(message, dict) or message.get("role") != "tool":
            continue
        content = message.get("content")
        if not isinstance(content, str):
            continue
        # The source map is the card's; the live loop never showed it.
        if message.get("name") in _SOURCE_MAP_TOOLS and "\n__RAG_SOURCES__:" in content:
            content = _strip_rag_sources_sentinel(content)
        extra = message.get("extra_content")
        suffix = extra.get(TOOL_MODEL_SUFFIX_KEY) if isinstance(extra, dict) else None
        suffix = suffix if isinstance(suffix, str) else ""
        # `in`: restored output may carry feedback after the nudge.
        nudge = (
            TOOL_ERROR_NUDGE if is_tool_error(content) and TOOL_ERROR_NUDGE not in content else ""
        )
        restored = {**message, "content": content}
        if nudge or suffix:
            # Before any envelope, as live: text after the image array breaks its parse.
            from core.inference.tools import _split_frontend_suffix
            body, envelope = _split_frontend_suffix(content, message.get("name"))
            restored["content"] = body + nudge + suffix + envelope
        if isinstance(extra, dict) and TOOL_MODEL_SUFFIX_KEY in extra:
            rest = {k: v for k, v in extra.items() if k != TOOL_MODEL_SUFFIX_KEY}
            if rest:
                restored["extra_content"] = rest
            else:
                restored.pop("extra_content", None)
        if restored != message:
            out[i] = restored
    return out


def _strip_mcp_ui_suffix(result: str) -> str:
    """The payload is one JSON line, so the scan stops there; images may follow."""
    marker = "\n__MCP_UI__:"
    start = result.rfind(marker)
    if start == -1:
        return result
    payload_start = start + len(marker)
    end = result.find("\n", payload_start)
    if end == -1:
        end = len(result)
    try:
        payload = json.loads(result[payload_start:end])
    except (ValueError, RecursionError):
        return result
    if not isinstance(payload, dict) or not isinstance(payload.get("resourceUri"), str):
        return result
    return (result[:start] + result[end:]).rstrip()


def _strip_files_sentinel(result: str) -> str:
    """Validated, not split on sight, so a tool quoting the marker does not lose the rest."""
    marker = "\n__FILES__:"
    start = result.rfind(marker)
    if start == -1:
        return result
    payload_start = start + len(marker)
    end = result.find("\n__", payload_start)
    if end == -1:
        end = len(result)
    try:
        entries = json.loads(result[payload_start:end])
    except (ValueError, TypeError, RecursionError):
        return result
    # Validate every entry: anything else is a tool that happened to print the marker.
    if not isinstance(entries, list) or not all(_is_file_entry(e) for e in entries):
        return result
    return result[:start] + result[end:]


def _is_file_entry(entry: object) -> bool:
    return (
        isinstance(entry, dict)
        and isinstance(entry.get("name"), str)
        and bool(entry.get("name"))
        and (entry.get("size") is None or isinstance(entry.get("size"), int))
    )


def _strip_images_sentinel(result: str) -> str:
    """Validated envelopes only; every one is stripped, and cut once so long MCP output stays linear."""
    marker = "\n__IMAGES__:"
    end = len(result)
    cut = -1
    while True:
        start = result.rfind(marker, 0, end)
        if start == -1:
            break
        try:
            images = json.loads(result[start + len(marker) : end])
        except (ValueError, RecursionError):
            break
        if not isinstance(images, list) or not images:
            break
        if not all(isinstance(image, str) and image for image in images):
            break
        cut = start
        end = start
    return result if cut == -1 else result[:cut].rstrip()


def _strip_rag_sources_sentinel(result: str) -> str:
    """Deliberately unbounded: size is no guard, since the gate on the emitting tools keeps MCP text out."""
    head, sep, payload = result.rpartition("\n__RAG_SOURCES__:")
    if not sep:
        return result
    try:
        sources = json.loads(payload)
    except (ValueError, RecursionError):
        return result
    if not isinstance(sources, list):
        return result
    return head.rstrip()


# Only these emit the file envelope; an MCP tool or fetched page ending in __FILES__ is content.
_SANDBOX_TOOLS = frozenset({"python", "terminal"})
# edit_file emits it too, for a file it created, and the media tools for the file they rendered.
_FILE_SENTINEL_TOOLS = _SANDBOX_TOOLS | {"edit_file"} | MEDIA_CHAT_TOOLS

# Only an MCP result can carry the UI envelope; mcp_client defuses tool-written ones.
_MCP_TOOL_PREFIX = "mcp__"

# Same rule for the other two envelopes. The image one is emitted by the sandbox tools
# through `_created_file_sentinels` and by Gemini's hosted code_execution through the
# provider; the source map by the retrieval tools that append `RAG_SOURCES_SENTINEL`. A
# document an MCP tool read, or a page that was fetched, ending in a well-formed one of
# either is content the model needs, and cutting it leaves the model reasoning over less
# than the card the user is looking at.
_IMAGE_SENTINEL_TOOLS = _SANDBOX_TOOLS | {"code_execution", "generate_image"}
_SOURCE_MAP_TOOLS = frozenset({"search_knowledge_base", "search_conversation"})
_WORKSPACE_TOOLS = _SANDBOX_TOOLS | {"edit_file", "view_image"}


def _reruns_after_new_work(tool_name: Any) -> bool:
    """An MCP tool can change state too (`list, create, list`), so it follows the workspace rerun rule (#10348)."""
    return tool_name in _WORKSPACE_TOOLS or str(tool_name or "").startswith(_MCP_TOOL_PREFIX)


# Cached in the clear for CLI reuse; masked before the model, and the mask has no prefix to
# re-match.
_STUDIO_API_KEY_RE = re.compile(
    # 8, not 32: a truncated result can end mid-key. Hex only, so `sk-unsloth-internal-...` survives.
    r"sk-unsloth-[0-9a-fA-F]{8,}"
    # `desktop-` + token_urlsafe(48); the floor keeps "desktop-app" out of it.
    r"|desktop-[A-Za-z0-9_-]{40,}"
)
_STUDIO_SECRET_MASK = "[redacted]"


def redact_studio_credentials(text: str) -> str:
    """Two substring scans run first: the regex alternation has no literal to anchor on, so most text skips it."""
    if "sk-unsloth-" not in text and "desktop-" not in text:
        return text
    return _STUDIO_API_KEY_RE.sub(_STUDIO_SECRET_MASK, text)


def strip_result_for_model(
    result: str,
    tool_name: "str | None" = None,
    *,
    redact: bool = True,
) -> str:
    """redact=False keeps the strip suffix-only for _split_frontend_suffix, which masking would break; the mask still applies later in model_message."""
    if tool_name is None or tool_name == "web_search":
        from .search_images import strip_images_suffix
        result = strip_images_suffix(result)
    # Always strip image bytes; provenance only decides whether they become image input.
    result = split_mcp_images(result)[0]
    # After the image strip, which leaves the UI envelope as the tail.
    if tool_name is None or tool_name.startswith(_MCP_TOOL_PREFIX):
        result = _strip_mcp_ui_suffix(result)
    if tool_name is None or tool_name in _FILE_SENTINEL_TOOLS:
        result = _strip_files_sentinel(result)
    if tool_name is None or tool_name in _IMAGE_SENTINEL_TOOLS:
        result = _strip_images_sentinel(result)
    if tool_name is None or tool_name in _SOURCE_MAP_TOOLS:
        result = _strip_rag_sources_sentinel(result)
    return redact_studio_credentials(result) if redact else result


def deferred_nudge_text(msgs: Sequence[dict]) -> str:
    """Body text without the role=user wrapper, so the in-exchange and user-message forms stay in sync."""
    return "\n\n".join(dict.fromkeys(msg["content"] for msg in msgs))


def append_deferred_nudges(conversation: list, msgs: Sequence[dict]) -> None:
    """Appended after the tool results, so a nudge never splits tool_calls from their role=tool replies."""
    if msgs:
        conversation.append({"role": "user", "content": deferred_nudge_text(msgs)})


def tool_call_limit_nudge(
    tool_calls: Sequence[Mapping[str, Any]],
    limit: int,
    *,
    final: bool = False,
    unavailable_tools: Collection[str] = (),
) -> dict:
    described = []
    for tool_call in tool_calls:
        function = tool_call.get("function") or {}
        arguments = function.get("arguments", {})
        if not isinstance(arguments, str):
            arguments = canonical_arguments_text(arguments)
        described.append(f"{function.get('name', '')} {arguments}")
    follow_up = (
        "Do not describe results you did not receive."
        if final
        else "Call them again if you still need their results, and do not describe results "
        "you did not receive."
    )
    if not final and unavailable_tools:
        retryable_names = sorted(
            {(call.get("function") or {}).get("name", "") for call in tool_calls}
            - set(unavailable_tools)
        )
        follow_up = (
            f"Do not retry {', '.join(sorted(unavailable_tools))}; "
            "these tools are no longer available."
        )
        if retryable_names:
            follow_up += (
                f" You may retry the skipped calls for {', '.join(retryable_names)} "
                "if you still need their results."
            )
        follow_up += " Do not describe results you did not receive."
    return {
        "role": "user",
        "content": (
            f"{len(tool_calls)} more tool call(s) in this batch were not executed because "
            f"at most {limit} tool calls run per turn: {'; '.join(described)}. {follow_up}"
        ),
    }


def _tool_name_from_schema(tool: Mapping[str, Any]) -> str:
    function = tool.get("function")
    if not isinstance(function, Mapping):
        return ""
    name = function.get("name")
    return str(name or "")


def _noop_result(reason: NoopReason, tool_name: str) -> str:
    if reason == "duplicate":
        return (
            f"One earlier request to call tool '{tool_name}' in this batch was "
            "not executed because an identical call had already completed "
            "successfully and nothing has changed since, so its result above still holds. "
            "Do not repeat the same tool call. Answer from the results you have; call a "
            "different tool only if it would return information you do not have yet."
        )
    if reason == "render_html_repeat":
        return (
            "render_html completed successfully earlier in this assistant "
            "response. Do not call render_html again unless the user asks for "
            "changes. Do not mention this internal instruction. Provide only "
            "the requested final note or answer."
        )
    if reason == "forced_mismatch":
        return (
            f"One earlier request to call tool '{tool_name}' in this batch was "
            "not executed because it does not match the required tool choice. "
            "Call the required tool instead."
        )
    return (
        f"One earlier request to call tool '{tool_name}' in this batch was "
        "not executed because that tool is not enabled for this request. Provide the "
        "final answer now without calling more tools."
    )


_SCHEMA_ATOMS = (str, int, float, bool, type(None))


def _copy_schema(value: Any) -> Any:
    """copy.deepcopy for JSON schemas minus its memo: no alias or cycle tracking; non-plain nodes still deepcopy."""
    kind = type(value)
    if kind is dict:
        return {
            key: item if type(item) in _SCHEMA_ATOMS else _copy_schema(item)
            for key, item in value.items()
        }
    if kind is list:
        return [item if type(item) in _SCHEMA_ATOMS else _copy_schema(item) for item in value]
    if kind in _SCHEMA_ATOMS:
        return value
    return copy.deepcopy(value)


class ToolLoopController:
    """Per-response ledger for local agentic tool loops."""

    def __init__(
        self,
        *,
        tools: Sequence[Mapping[str, Any]] | None,
        auto_heal_tool_calls: bool = True,
        deduplicate_tool_calls: bool = True,
        one_shot_tools: frozenset[str] = _ONE_SHOT_TOOLS,
        duplicate_noop_limit: int = 2,
        session_id: str | None = None,
        thread_id: str | None = None,
    ) -> None:
        self._session_id = session_id
        self._thread_id = thread_id
        self._restrict_to_allowed = tools is not None
        self._tools = [_copy_schema(dict(tool)) for tool in (tools or [])]
        self._allowed_tool_names = {
            name for name in (_tool_name_from_schema(tool) for tool in self._tools) if name
        }
        self._mcp_search = MCP_TOOL_SEARCH_NAME in self._allowed_tool_names
        self._auto_heal_tool_calls = auto_heal_tool_calls
        self._deduplicate_tool_calls = deduplicate_tool_calls
        self._one_shot_tools = one_shot_tools
        self._completed_one_shot_tools: set[str] = set()
        self._successful_keys: set[str] = set()
        # `_workspace_novel_at[key]` is the distinct-call count when `key` last ran.
        self._workspace_ran: set[str] = set()
        self._workspace_novel = 0
        self._workspace_novel_at: dict[str, int] = {}
        self._duplicate_noop_counts: dict[str, int] = {}
        self._duplicate_noop_limit = max(1, duplicate_noop_limit)
        self._history: list[_ToolCallRecord] = []
        self._force_final_answer = False
        self._awaiting_user = False

    @property
    def awaiting_user(self) -> bool:
        """A result in the latest batch said only the user can unblock this turn."""
        return self._awaiting_user

    def begin_batch(self) -> None:
        self._awaiting_user = False

    @property
    def history(self) -> tuple[_ToolCallRecord, ...]:
        return tuple(self._history)

    @property
    def force_final_answer(self) -> bool:
        """True once a terminal no-op should transition to a no-tools pass."""
        return self._force_final_answer

    def has_active_tools(self) -> bool:
        """bool(active_tools()) without copying a schema."""
        return not self._force_final_answer and any(
            _tool_name_from_schema(tool) not in self._completed_one_shot_tools
            for tool in self._tools
        )

    def active_tools(self, *, include_deferred: bool = False) -> list[dict[str, Any]]:
        """Return prompt tools, optionally including deferred schemas for decoding."""
        if self._force_final_answer:
            return []
        active: list[dict[str, Any]] = []
        tools = self._tools
        if include_deferred and self._mcp_search:
            declared = {_tool_name_from_schema(tool) for tool in tools}
            tools = tools + [
                spec
                for name in sorted(self._allowed_tool_names - declared)
                if (spec := _mcp_tool_spec(name)) is not None
            ]
        for tool in tools:
            name = _tool_name_from_schema(tool)
            if name in self._completed_one_shot_tools:
                continue
            active.append(_copy_schema(tool))
        return active

    def prepare_call(
        self,
        tool_call: Mapping[str, Any],
        *,
        forced: bool = False,
        provisional: bool = False,
        allowed_tool_names: Collection[str] | None = None,
    ) -> ToolCallDecision:
        """Classify a parsed tool call before any visible event is yielded."""
        function = tool_call.get("function")
        function = function if isinstance(function, Mapping) else {}
        tool_name = str(function.get("name") or "").strip()
        name_healed = False
        if self._auto_heal_tool_calls and tool_name not in self._allowed_tool_names:
            canonical = _canonical_tool_name(tool_name, self._allowed_tool_names)
            if canonical is not None:
                tool_name, name_healed = canonical, True
        # Deferred schemas must not shift the cached prompt prefix.
        extra_schema = None
        if (
            self._mcp_search
            and tool_name.startswith(MCP_TOOL_PREFIX)
            and tool_name not in {_tool_name_from_schema(tool) for tool in self._tools}
        ):
            extra_schema = _mcp_tool_spec(tool_name)
            if extra_schema is not None:
                self._allowed_tool_names.add(tool_name)
        coerced = coerce_tool_arguments(
            function.get("arguments", {}),
            heal = self._auto_heal_tool_calls,
            tool_name = tool_name,
            tool_schemas = self._tools + ([extra_schema] if extra_schema is not None else []),
        )
        arguments = coerced.arguments
        if tool_name == "web_search" and UNPARSED_ARGUMENTS_KEY not in arguments:
            from core.inference.tools import canonicalize_web_search_arguments
            arguments = canonicalize_web_search_arguments(arguments)
        key = canonical_tool_call_key(tool_name, arguments)
        mcp = mcp_display_parts(tool_name)
        provenance = tool_event_provenance(
            healed = coerced.healed or name_healed,
            forced = forced,
            provisional = provisional,
            mcp_server = mcp[0] if mcp else None,
            mcp_tool = mcp[1] if mcp else None,
        )
        action: ToolAction = "execute"
        noop = ""
        if tool_name in self._completed_one_shot_tools:
            action = "render_html_repeat"
            noop = _noop_result("render_html_repeat", tool_name)
        elif allowed_tool_names is not None and tool_name not in allowed_tool_names:
            action = "forced_mismatch"
            noop = _noop_result("forced_mismatch", tool_name)
        elif self._restrict_to_allowed and tool_name not in self._allowed_tool_names:
            action = "disabled"
            noop = _noop_result("disabled", tool_name)
        elif (
            self._deduplicate_tool_calls
            and key in self._successful_keys
            and not repeatable(tool_name)
            and tool_name != MCP_TOOL_SEARCH_NAME
        ):
            # Not the browser tools: each acts on or reads the page as it is now, so a second
            # scroll down or a snapshot after a click is new work, and two such no-ops ended the turn.
            # Nor the media tools: the same prompt again is another image with a fresh seed.
            action = "duplicate"
            noop = _noop_result("duplicate", tool_name)

        return ToolCallDecision(
            action = action,
            tool_name = tool_name,
            arguments = arguments,
            tool_call_id = str(tool_call.get("id") or ""),
            card_call_id = str(tool_call.get("card_id") or ""),
            key = key,
            provenance = provenance,
            status_text = status_for_tool(tool_name, arguments),
            noop_result = noop,
        )

    def reprepare_call(
        self,
        decision: ToolCallDecision,
        *,
        forced: bool = False,
        provisional: bool = False,
        allowed_tool_names: Collection[str] | None = None,
    ) -> ToolCallDecision:
        """Replay, status and duplicate key must describe the arguments that actually execute."""
        tool_call = decision.as_assistant_tool_call()
        if decision.card_call_id:
            tool_call["card_id"] = decision.card_call_id
        refreshed = self.prepare_call(
            tool_call,
            forced = forced,
            provisional = provisional,
            allowed_tool_names = allowed_tool_names,
        )
        # Keep first-parse provenance, e.g. whether a local model's bare argument was healed.
        refreshed.provenance.update(decision.provenance)
        return refreshed

    def record_result(self, decision: ToolCallDecision, result: Any) -> ToolCallCompletion:
        """Record a real tool execution and return model/frontend payload helpers."""
        result_text = result if isinstance(result, str) else str(result)
        failed = is_tool_error(result_text)
        # Sticky for the batch: a parallel call that succeeds does not unblock the user.
        self._awaiting_user = self._awaiting_user or awaits_user(result_text)
        result_text = self._cap_result(result_text, decision.tool_name)
        self._history.append(
            _ToolCallRecord(
                key = decision.key,
                is_error = failed,
                executed = True,
                action = decision.action,
            )
        )
        # One rerun per piece of NEW work, not per call: `read, edit, read, edit` would
        # otherwise apply the edit twice. Here as well as in the prefilters, which a
        # structured batch skips. A failed command can still have written, so it counts too.
        if _reruns_after_new_work(decision.tool_name):
            # A repeatable writer (an unseeded generator) makes something new on every run.
            if not reads_only(decision.tool_name) and (
                decision.key not in self._workspace_ran or repeatable(decision.tool_name)
            ):
                self._workspace_ran.add(decision.key)
                self._workspace_novel += 1
            stale = {
                key
                for key in self._successful_keys
                if _reruns_after_new_work(key.partition(":")[0])
                and self._workspace_novel_at.get(key, 0) < self._workspace_novel
            }
            self._successful_keys -= stale
            for key in stale:
                self._duplicate_noop_counts.pop(key, None)
            self._workspace_novel_at[decision.key] = self._workspace_novel
        if not failed:
            self._successful_keys.add(decision.key)
            if self._mcp_search and decision.tool_name == MCP_TOOL_SEARCH_NAME:
                for spec in _mcp_tool_search_specs(result_text):
                    name = _tool_name_from_schema(spec) if isinstance(spec, Mapping) else None
                    if name:
                        self._allowed_tool_names.add(name)
            elif decision.tool_name.startswith(MCP_TOOL_PREFIX):
                # Also while the catalog is listed in full, for a later turn that defers it.
                self._remember_mcp_tools([decision.tool_name])
            if decision.tool_name in self._one_shot_tools:
                self._completed_one_shot_tools.add(decision.tool_name)
        return ToolCallCompletion(
            decision = decision,
            result = result_text,
            is_error = failed,
            executed = True,
        )

    def _remember_mcp_tools(self, names) -> None:
        if not names:
            return
        try:
            from core.inference.tools import mcp_record_loaded_tools  # noqa: PLC0415 -- import cycle
            mcp_record_loaded_tools(self._thread_id, names)
        except Exception:  # noqa: BLE001 -- remembering for later turns must never break this one
            pass

    def _cap_result(self, text: str, tool_name: str | None) -> str:
        """The card and the model get the same capped body; the frontend envelope stays whole."""
        from core.inference.tools import (  # noqa: PLC0415 -- import cycle
            _hard_cap_chars,
            _split_frontend_suffix,
            cap_tool_text,
        )

        if len(text) <= _hard_cap_chars():
            return text
        body, suffix = _split_frontend_suffix(text, tool_name)
        capped = cap_tool_text(
            body,
            session_id = self._session_id,
            thread_id = self._thread_id,
            readers = frozenset(self._allowed_tool_names),
        )
        return text if capped is body else capped + suffix

    def record_noop(self, decision: ToolCallDecision) -> ToolCallCompletion:
        """Record a controller no-op without creating visible tool output."""
        self._history.append(
            _ToolCallRecord(
                key = decision.key,
                is_error = False,
                executed = False,
                action = decision.action,
            )
        )
        if decision.action == "duplicate":
            duplicate_count = self._duplicate_noop_counts.get(decision.key, 0) + 1
            self._duplicate_noop_counts[decision.key] = duplicate_count
            if duplicate_count >= self._duplicate_noop_limit:
                self._force_final_answer = True
        elif decision.action in ("disabled", "render_html_repeat"):
            self._force_final_answer = True
        return ToolCallCompletion(
            decision = decision,
            result = decision.noop_result,
            is_error = False,
            executed = False,
        )