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.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
# 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,
)