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.

Studio: cap tool-result text at 256K chars, spill the full output to the sandbox (#11430)

Jyotirmoy Roy6f4c16250df2
diff --git a/studio/backend/core/inference/llama_cpp.py b/studio/backend/core/inference/llama_cpp.py
index d18a90f42e8..1c0f6cfe8db 100644
--- a/studio/backend/core/inference/llama_cpp.py
+++ b/studio/backend/core/inference/llama_cpp.py
@@ -36603,6 +36603,8 @@ class LlamaCppBackend:
tool_controller = ToolLoopController(
tools = controller_tools,
auto_heal_tool_calls = auto_heal_tool_calls,
+ session_id = session_id,
+ thread_id = thread_id,
)
def _tool_succeeded(tool_name: str) -> bool:
diff --git a/studio/backend/core/inference/safetensors_agentic.py b/studio/backend/core/inference/safetensors_agentic.py
index b17429fe3d6..2f5f8ce3327 100644
--- a/studio/backend/core/inference/safetensors_agentic.py
+++ b/studio/backend/core/inference/safetensors_agentic.py
@@ -748,6 +748,8 @@ def run_safetensors_tool_loop(
tool_controller = ToolLoopController(
tools = (None if unrestricted_tools else _authorized),
auto_heal_tool_calls = auto_heal_tool_calls,
+ session_id = session_id,
+ thread_id = thread_id,
)
# RAG: cap knowledge-base searches per assistant turn (controller-agnostic).
kb_search_count = 0
diff --git a/studio/backend/core/inference/studio_tool_loop.py b/studio/backend/core/inference/studio_tool_loop.py
index 3883fb65961..6b22b7d991d 100644
--- a/studio/backend/core/inference/studio_tool_loop.py
+++ b/studio/backend/core/inference/studio_tool_loop.py
@@ -1339,6 +1339,8 @@ async def stream_with_studio_tools(
controller = ToolLoopController(
tools = tools,
auto_heal_tool_calls = policy.auto_heal is not False,
+ session_id = session_id,
+ thread_id = thread_id,
)
tool_hint = ", ".join(sorted(allowed_tool_names))
reprompts = 0
diff --git a/studio/backend/core/inference/tool_loop_controller.py b/studio/backend/core/inference/tool_loop_controller.py
index 1e7b6483ae7..07a95186b61 100644
--- a/studio/backend/core/inference/tool_loop_controller.py
+++ b/studio/backend/core/inference/tool_loop_controller.py
@@ -1161,7 +1161,11 @@ class ToolLoopController:
auto_heal_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.deepcopy(dict(tool)) for tool in (tools or [])]
self._allowed_tool_names = {
@@ -1263,6 +1267,7 @@ class ToolLoopController:
"""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)
+ result_text = self._cap_result(result_text, decision.tool_name)
self._history.append(
_ToolCallRecord(
key = decision.key,
@@ -1302,6 +1307,25 @@ class ToolLoopController:
executed = True,
)
+ 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(
diff --git a/studio/backend/core/inference/tools.py b/studio/backend/core/inference/tools.py
index 76b6945013e..9a4c4680512 100644
--- a/studio/backend/core/inference/tools.py
+++ b/studio/backend/core/inference/tools.py
@@ -20510,6 +20510,65 @@ def _split_frontend_suffix(text: str, name: "str | None") -> "tuple[str, str]":
return body, text[len(body) :]
+MAX_TOOL_TEXT_CHARS = _env_int("UNSLOTH_TOOL_RESULT_HARD_CAP_CHARS", 256_000)
+_TOOL_TEXT_READERS = frozenset({"terminal", "python"})
+
+
+def _hard_cap_chars() -> int:
+ """Never below the window-aware cap plus its notice, so output `_truncate` already cut (and
+ spilled) passes through with its own spill reference intact."""
+ return max(MAX_TOOL_TEXT_CHARS, _MAX_OUTPUT_CHARS + 4_000)
+
+
+def _tool_text_notice_head() -> str:
+ return f"\n\n... (tool result truncated to {_hard_cap_chars():,} chars for the model;"
+
+
+def _tool_text_search_hint(path: str, readers: "frozenset[str]") -> str:
+ ways = []
+ if "terminal" in readers and _posix_tools_available():
+ ways += [f"grep -n 'pattern' {path}", f"sed -n '1,200p' {path}"]
+ elif "terminal" in readers:
+ ways.append(f'findstr /n "pattern" {path.replace("/", chr(92))}')
+ if "python" in readers:
+ ways.append(f"open({path!r}) in python")
+ return "Search it instead of re-running the call, e.g. " + ", or ".join(ways)
+
+
+def cap_tool_text(
+ text: str,
+ *,
+ session_id: "str | None" = None,
+ thread_id: "str | None" = None,
+ readers: "frozenset[str]" = frozenset(),
+) -> str:
+ """Unconditional floor (``UNSLOTH_TOOL_RESULT_HARD_CAP_CHARS``); spills when a reader tool exists."""
+ limit = _hard_cap_chars()
+ if len(text) <= limit:
+ return text
+ head = _head_whole_lines(text, limit)[0]
+ readers = readers & _TOOL_TEXT_READERS
+ if readers and session_id and _spill_scope(session_id, thread_id) is not None:
+ try:
+ workdir = _get_workdir(session_id)
+ except Exception: # noqa: BLE001 -- no sandbox means the plain notice
+ logger.debug("tool text spill: no workdir", exc_info = True)
+ workdir = None
+ from .tool_loop_controller import redact_studio_credentials # noqa: PLC0415
+
+ # Masked like the card and the model copy: the model reads this file.
+ spill, complete = _spill_full_output(
+ redact_studio_credentials(text), workdir, _spill_scope(session_id, thread_id)
+ )
+ if spill is not None:
+ return (
+ head
+ + f"{_tool_text_notice_head()} {_spill_phrase(spill, complete)} in the working "
+ f"directory. {_tool_text_search_hint(spill, readers)}.)"
+ )
+ return head + f"{_tool_text_notice_head()} the full output is not retained in model context.)"
+
+
def _head_whole_lines(text: str, limit: int) -> "tuple[str, bool]":
"""``text`` cut to at most ``limit`` characters, and whether it ended on a line break.
diff --git a/studio/backend/tests/test_tool_loop_controller.py b/studio/backend/tests/test_tool_loop_controller.py
index 21aa0df82e2..6f61834470b 100644
--- a/studio/backend/tests/test_tool_loop_controller.py
+++ b/studio/backend/tests/test_tool_loop_controller.py
@@ -37,7 +37,17 @@ from core.inference.tool_loop_controller import (
tool_event_provenance,
)
from core.inference.tool_call_parser import TOOL_ERROR_NUDGE, parse_tool_calls_from_text
-from core.inference.tools import ALL_TOOLS, _mcp_specs_for_server, execute_tool
+from core.inference.tools import (
+ ALL_TOOLS,
+ MAX_TOOL_TEXT_CHARS,
+ _mcp_specs_for_server,
+ _tool_text_notice_head,
+ cap_tool_text,
+ execute_tool,
+)
+
+
+_NOTICE = _tool_text_notice_head() + " the full output is not retained in model context.)"
def test_append_deferred_nudges_merges_deduped_into_one_message():
@@ -782,3 +792,190 @@ def test_tool_call_limit_nudge_keeps_long_arguments_whole():
[{"function": {"name": "python", "arguments": json.dumps({"code": code})}}], 8
)
assert json.dumps({"code": code}) in notice["content"]
+
+
+def test_cap_tool_text_passes_results_at_or_under_the_floor_through_unchanged():
+ assert cap_tool_text("short result") == "short result"
+ exact = "x" * MAX_TOOL_TEXT_CHARS
+ assert cap_tool_text(exact) is exact
+
+
+def test_cap_tool_text_cuts_oversized_text_at_a_nearby_line_break_and_appends_notice():
+ line = "x" * 100 + "\n"
+ big = line * (MAX_TOOL_TEXT_CHARS // len(line) + 100)
+ out = cap_tool_text(big)
+
+ assert out.endswith(_NOTICE)
+ body = out[: -len(_NOTICE)]
+ assert big.startswith(body)
+ assert len(body) < MAX_TOOL_TEXT_CHARS
+ assert big[len(body)] == "\n"
+ assert len(out) <= MAX_TOOL_TEXT_CHARS + len(_NOTICE)
+
+
+def test_cap_tool_text_cuts_a_single_line_mid_line_when_no_break_is_near():
+ big = "y" * (MAX_TOOL_TEXT_CHARS + 500)
+ out = cap_tool_text(big)
+
+ assert out.endswith(_NOTICE)
+ body = out[: -len(_NOTICE)]
+ assert body == big[:MAX_TOOL_TEXT_CHARS]
+
+
+def test_text_that_merely_quotes_the_notice_is_still_capped():
+ big = "x" * (MAX_TOOL_TEXT_CHARS + 50_000) + _NOTICE
+ assert cap_tool_text(big) == "x" * MAX_TOOL_TEXT_CHARS + _NOTICE
+
+
+def test_an_oversized_result_is_capped_for_the_card_and_the_model_alike():
+ controller = ToolLoopController(tools = [_tool("terminal")])
+ decision = controller.prepare_call(_call("terminal", {"command": "cat big.log"}))
+ huge = "line of output\n" * 400_000
+ completion = controller.record_result(decision, huge)
+
+ content = completion.tool_message()["content"]
+ assert completion.tool_end_payload()["result"] == content
+ assert content.endswith(_NOTICE)
+ body = content[: -len(_NOTICE)]
+ assert len(body) <= MAX_TOOL_TEXT_CHARS
+ assert huge.startswith(body)
+ assert huge[len(body)] == "\n"
+
+
+def test_the_cap_keeps_the_card_envelope_whole_and_off_the_model():
+ envelope = '\n__WEB_IMAGES__:[{"id": "a1b2c3d4e5f6", "title": "A chart", "domain": "example.com", "source": "https://example.com/a.png"}]'
+ huge = ("z" * (MAX_TOOL_TEXT_CHARS + 2000)) + envelope
+ controller = ToolLoopController(tools = [_tool("web_search")])
+ completion = controller.record_result(
+ controller.prepare_call(_call("web_search", {"url": "https://example.com/a"})), huge
+ )
+
+ capped = "z" * MAX_TOOL_TEXT_CHARS + _NOTICE
+ assert completion.tool_end_payload()["result"] == capped + envelope
+ assert completion.tool_message()["content"] == capped
+
+
+def _sandbox(tmp_path, monkeypatch):
+ import core.inference.tools as tools
+
+ records = tmp_path / "records"
+ records.mkdir()
+ workdir = tmp_path / "sandbox"
+ workdir.mkdir()
+ monkeypatch.setattr(tools, "_spill_records_dir", lambda: str(records))
+ monkeypatch.setattr(tools, "_get_workdir", lambda session_id = None: str(workdir))
+ return workdir
+
+
+def _spilled(
+ names,
+ result,
+ session_id = "chat-1",
+):
+ controller = ToolLoopController(
+ tools = [_tool(name) for name in names], session_id = session_id, thread_id = "t1"
+ )
+ return controller.record_result(
+ controller.prepare_call(_call(names[0], {"server": "x", "q": "y"})), result
+ )
+
+
+def test_an_oversized_result_is_spilled_and_the_model_is_told_how_to_search_it(_sandbox):
+ huge = "".join(f"row {i}\n" for i in range(60_000))
+ content = _spilled(["mcp__docs__dump", "terminal"], huge).tool_message()["content"]
+
+ notice = content[content.index(_tool_text_notice_head()) :]
+ path = notice.split("saved to ")[1].split(" ")[0]
+ assert (_sandbox / path).read_text() == huge
+ assert f"grep -n 'pattern' {path}" in notice
+ assert f"sed -n '1,200p' {path}" in notice
+ assert "open(" not in notice
+
+
+def test_the_hint_names_only_the_reader_the_model_has(_sandbox):
+ huge = "q" * (MAX_TOOL_TEXT_CHARS + 1)
+ content = _spilled(["mcp__docs__dump", "python"], huge).tool_message()["content"]
+ assert "open('.unsloth_tool_output/" in content
+ assert "grep" not in content
+
+
+def test_a_cmd_only_windows_host_gets_findstr_with_a_backslash_path(_sandbox, monkeypatch):
+ import core.inference.tools as tools
+
+ monkeypatch.setattr(tools, "_posix_tools_available", lambda: False)
+ huge = "q" * (MAX_TOOL_TEXT_CHARS + 1)
+ content = _spilled(["mcp__docs__dump", "terminal"], huge).tool_message()["content"]
+ assert 'findstr /n "pattern" .unsloth_tool_output\\' in content
+ assert "grep" not in content
+
+
+def test_no_reader_tool_or_a_shared_sandbox_gets_the_plain_notice(_sandbox):
+ huge = "q" * (MAX_TOOL_TEXT_CHARS + 1)
+ plain = "q" * MAX_TOOL_TEXT_CHARS + _NOTICE
+ assert _spilled(["mcp__docs__dump"], huge).tool_message()["content"] == plain
+ assert (
+ _spilled(["mcp__docs__dump", "terminal"], huge, session_id = None).tool_message()["content"]
+ == plain
+ )
+ assert not (_sandbox / ".unsloth_tool_output").exists()
+
+
+def test_model_message_leaves_an_already_capped_result_alone():
+ big = "a" * (MAX_TOOL_TEXT_CHARS + 10_000)
+ already = cap_tool_text(big)
+ controller = ToolLoopController(tools = [_tool("terminal")])
+ completion = controller.record_result(
+ controller.prepare_call(_call("terminal", {"command": "ls"})), already
+ )
+
+ assert completion.tool_message()["content"] == already
+
+
+def test_model_message_keeps_the_error_nudge_on_an_oversized_error_result():
+ huge = "Error: " + "e" * (MAX_TOOL_TEXT_CHARS + 10_000)
+ controller = ToolLoopController(tools = [_tool("terminal")])
+ completion = controller.record_result(
+ controller.prepare_call(_call("terminal", {"command": "ls"})), huge
+ )
+
+ assert completion.is_error
+ assert completion.tool_message()["content"] == cap_tool_text(huge) + TOOL_ERROR_NUDGE
+
+
+def test_the_hard_cap_is_tunable(monkeypatch):
+ import core.inference.tools as tools
+
+ monkeypatch.setenv("UNSLOTH_TOOL_RESULT_HARD_CAP_CHARS", "1000")
+ assert tools._env_int("UNSLOTH_TOOL_RESULT_HARD_CAP_CHARS", 256_000) == 1000
+ monkeypatch.setattr(tools, "MAX_TOOL_TEXT_CHARS", 50_000)
+ completion = _spilled(["mcp__docs__dump"], "w" * 60_000)
+ content = completion.tool_message()["content"]
+ assert content == "w" * 50_000 + _tool_text_notice_head() + (
+ " the full output is not retained in model context.)"
+ )
+ assert "truncated to 50,000 chars" in content
+
+
+def test_the_spill_masks_studio_credentials_like_the_model_copy(_sandbox):
+ key = "sk-unsloth-" + "ab12" * 8
+ huge = f"token {key}\n" + "r\n" * (MAX_TOOL_TEXT_CHARS // 2 + 10)
+ content = _spilled(["mcp__docs__dump", "terminal"], huge).tool_message()["content"]
+
+ path = content.split("saved to ")[1].split(" ")[0]
+ spilled = (_sandbox / path).read_text()
+ assert key not in spilled and key not in content
+ assert spilled.startswith("token [redacted]")
+
+
+def test_a_hard_cap_below_the_window_cap_leaves_truncated_terminal_output_alone(monkeypatch):
+ import core.inference.tools as tools
+
+ monkeypatch.setattr(tools, "MAX_TOOL_TEXT_CHARS", 1000)
+ already = tools._truncate("t\n" * 50_000, workdir = None)
+ assert len(already) > 1000
+ controller = ToolLoopController(tools = [_tool("terminal")])
+ completion = controller.record_result(
+ controller.prepare_call(_call("terminal", {"command": "yes t"})), already
+ )
+ assert completion.tool_message()["content"] == already