feat: implement handling for large tool results with overflow file writing and read tool integration

Author: Soulter

astrbot/core/agent/runners/tool_loop_agent_runner.py

@@ -4,9 +4,11 @@
 import time
 import traceback
 import typing as T
+import uuid
 from collections.abc import AsyncIterator
 from contextlib import suppress
 from dataclasses import dataclass, field
+from pathlib import Path
 
 from mcp.types import (
     BlobResourceContents,
@@ -25,7 +27,7 @@
 
 from astrbot import logger
 from astrbot.core.agent.message import ImageURLPart, TextPart, ThinkPart
-from astrbot.core.agent.tool import ToolSet
+from astrbot.core.agent.tool import FunctionTool, ToolSet
 from astrbot.core.agent.tool_image_cache import tool_image_cache
 from astrbot.core.exceptions import EmptyModelOutputError
 from astrbot.core.message.components import Json
@@ -45,7 +47,7 @@
 from ..context.compressor import ContextCompressor
 from ..context.config import ContextConfig
 from ..context.manager import ContextManager
-from ..context.token_counter import TokenCounter
+from ..context.token_counter import EstimateTokenCounter, TokenCounter
 from ..hooks import BaseAgentRunHooks
 from ..message import AssistantMessageSegment, Message, ToolCallMessageSegment
 from ..response import AgentResponseData, AgentStats
@@ -97,6 +99,8 @@ class _ToolExecutionInterrupted(Exception):
 
 
 class ToolLoopAgentRunner(BaseAgentRunner[TContext]):
+    TOOL_RESULT_MAX_ESTIMATED_TOKENS = 27_500
+    TOOL_RESULT_PREVIEW_MAX_ESTIMATED_TOKENS = 7000
     EMPTY_OUTPUT_RETRY_ATTEMPTS = 3
     EMPTY_OUTPUT_RETRY_WAIT_MIN_S = 1
     EMPTY_OUTPUT_RETRY_WAIT_MAX_S = 4
@@ -151,6 +155,11 @@ class ToolLoopAgentRunner(BaseAgentRunner[TContext]):
         "Otherwise, change strategy, adjust arguments, or explain the limitation "
         "to the user."
     )
+    TOOL_RESULT_OVERFLOW_NOTICE_TEMPLATE = (
+        "Truncated tool output preview shown above. "
+        "The tool output was too large to include directly and was written to "
+        "`{overflow_path}`. Use {read_tool_hint} with a narrower window to inspect it."
+    )
 
     def _get_persona_custom_error_message(self) -> str | None:
         """Read persona-level custom error message from event extras when available."""
@@ -206,6 +215,8 @@ async def reset(
         custom_compressor: ContextCompressor | None = None,
         tool_schema_mode: str | None = "full",
         fallback_providers: list[Provider] | None = None,
+        tool_result_overflow_dir: str | None = None,
+        read_tool: FunctionTool | None = None,
         **kwargs: T.Any,
     ) -> None:
         self.req = request
@@ -217,6 +228,9 @@ async def reset(
         self.truncate_turns = truncate_turns
         self.custom_token_counter = custom_token_counter
         self.custom_compressor = custom_compressor
+        self.tool_result_overflow_dir = tool_result_overflow_dir
+        self.read_tool = read_tool
+        self._tool_result_token_counter = EstimateTokenCounter()
         # we will do compress when:
         # 1. before requesting LLM
         # TODO: 2. after LLM output a tool call
@@ -298,6 +312,103 @@ async def reset(
         self.stats = AgentStats()
         self.stats.start_time = time.time()
 
+    def _read_tool_hint(self) -> str:
+        if self.read_tool is not None:
+            return f"`{self.read_tool.name}`"
+        return "the available file-read tool"
+
+    async def _write_tool_result_overflow_file(
+        self,
+        *,
+        tool_call_id: str,
+        content: str,
+    ) -> str:
+        if self.tool_result_overflow_dir is None:
+            raise ValueError("tool_result_overflow_dir is not configured")
+
+        overflow_dir = Path(self.tool_result_overflow_dir).resolve(strict=False)
+        safe_tool_call_id = (
+            "".join(
+                ch if ch.isalnum() or ch in {"-", "_", "."} else "_"
+                for ch in tool_call_id
+            ).strip("._")
+            or "tool_call"
+        )
+        file_name = f"{safe_tool_call_id}_{uuid.uuid4().hex[:8]}.txt"
+        overflow_path = overflow_dir / file_name
+
+        def _run() -> str:
+            overflow_dir.mkdir(parents=True, exist_ok=True)
+            overflow_path.write_text(content, encoding="utf-8")
+            return str(overflow_path)
+
+        return await asyncio.to_thread(_run)
+
+    async def _materialize_large_tool_result(
+        self,
+        *,
+        tool_call_id: str,
+        content: str,
+    ) -> str:
+        if self.tool_result_overflow_dir is None or self.read_tool is None:
+            return content
+
+        estimated_tokens = self._tool_result_token_counter.count_tokens(
+            [Message(role="tool", content=content, tool_call_id=tool_call_id)]
+        )
+        if estimated_tokens <= self.TOOL_RESULT_MAX_ESTIMATED_TOKENS:
+            return content
+
+        preview = self._truncate_tool_result_preview(content, tool_call_id=tool_call_id)
+        try:
+            overflow_path = await self._write_tool_result_overflow_file(
+                tool_call_id=tool_call_id,
+                content=content,
+            )
+        except Exception as exc:
+            logger.warning(
+                "Failed to spill oversized tool result for %s: %s",
+                tool_call_id,
+                exc,
+                exc_info=True,
+            )
+            error_notice = (
+                "Tool output exceeded the inline result limit "
+                f"({estimated_tokens} estimated tokens > "
+                f"{self.TOOL_RESULT_MAX_ESTIMATED_TOKENS}) and could not be written "
+                f"to `{self.tool_result_overflow_dir}`: {exc}"
+            )
+            if not preview:
+                return error_notice
+            return f"{preview}\n\n{error_notice}"
+
+        notice = self.TOOL_RESULT_OVERFLOW_NOTICE_TEMPLATE.format(
+            overflow_path=overflow_path,
+            read_tool_hint=self._read_tool_hint(),
+        )
+        if not preview:
+            return notice
+        return f"{preview}\n\n{notice}"
+
+    def _truncate_tool_result_preview(
+        self,
+        content: str,
+        *,
+        tool_call_id: str,
+    ) -> str:
+        preview = content
+        while preview:
+            estimated_tokens = self._tool_result_token_counter.count_tokens(
+                [Message(role="tool", content=preview, tool_call_id=tool_call_id)]
+            )
+            if estimated_tokens <= self.TOOL_RESULT_PREVIEW_MAX_ESTIMATED_TOKENS:
+                return preview
+            next_len = len(preview) // 2
+            if next_len <= 0:
+                break
+            preview = preview[:next_len]
+        return preview
+
     async def _iter_llm_responses(
         self, *, include_model: bool = True
     ) -> T.AsyncGenerator[LLMResponse, None]:
@@ -933,9 +1044,14 @@ def _append_tool_call_result(tool_call_id: str, content: str) -> None:
                                         "The tool has returned a data type that is not supported."
                                     )
                         if result_parts:
+                            inline_result = "\n\n".join(result_parts)
+                            inline_result = await self._materialize_large_tool_result(
+                                tool_call_id=func_tool_id,
+                                content=inline_result,
+                            )
                             _append_tool_call_result(
                                 func_tool_id,
-                                "\n\n".join(result_parts)
+                                inline_result
                                 + self._build_repeated_tool_call_guidance(
                                     func_tool_name, tool_call_streak
                                 ),

astrbot/core/astr_main_agent.py

@@ -81,7 +81,10 @@
     TavilyWebSearchTool,
     normalize_legacy_web_search_config,
 )
-from astrbot.core.utils.astrbot_path import get_astrbot_workspaces_path
+from astrbot.core.utils.astrbot_path import (
+    get_astrbot_system_tmp_path,
+    get_astrbot_workspaces_path,
+)
 from astrbot.core.utils.file_extract import extract_file_moonshotai
 from astrbot.core.utils.llm_metadata import LLM_METADATAS
 from astrbot.core.utils.media_utils import (
@@ -1471,6 +1474,14 @@ async def build_main_agent(
         fallback_providers=_get_fallback_chat_providers(
             provider, plugin_context, config.provider_settings
         ),
+        tool_result_overflow_dir=(
+            get_astrbot_system_tmp_path()
+            if req.func_tool and req.func_tool.get_tool("astrbot_file_read_tool")
+            else None
+        ),
+        read_tool=(
+            req.func_tool.get_tool("astrbot_file_read_tool") if req.func_tool else None
+        ),
     )
 
     if apply_reset:

astrbot/core/computer/file_read_utils.py

@@ -182,8 +182,22 @@ def detect_text_encoding(sample: bytes) -> str | None:
     for encoding in _TEXT_ENCODINGS:
         try:
             decoded = sample.decode(encoding)
-        except UnicodeDecodeError:
-            continue
+        except UnicodeDecodeError as exc:
+            # Probe samples can end in the middle of a multibyte sequence.
+            # When the decode failure only happens at the sample tail, trim a few
+            # bytes and retry so UTF-8 text is not misclassified as binary.
+            if exc.start >= len(sample) - 4:
+                decoded = ""
+                for trim_bytes in range(1, min(4, len(sample)) + 1):
+                    try:
+                        decoded = sample[:-trim_bytes].decode(encoding)
+                        break
+                    except UnicodeDecodeError:
+                        continue
+                if not decoded:
+                    continue
+            else:
+                continue
         if _looks_like_text(decoded):
             return encoding
 

astrbot/core/star/context.py

@@ -36,6 +36,7 @@
     PlatformAdapterType,
 )
 from astrbot.core.subagent_orchestrator import SubAgentOrchestrator
+from astrbot.core.utils.astrbot_path import get_astrbot_system_tmp_path
 
 from ..exceptions import ProviderNotFoundError
 from .filter.command import CommandFilter
@@ -232,6 +233,13 @@ async def tool_loop_agent(
             for k, v in kwargs.items()
             if k not in ["stream", "agent_hooks", "agent_context"]
         }
+        if request.func_tool and request.func_tool.get_tool("astrbot_file_read_tool"):
+            other_kwargs.setdefault(
+                "tool_result_overflow_dir", get_astrbot_system_tmp_path()
+            )
+            other_kwargs.setdefault(
+                "read_tool", request.func_tool.get_tool("astrbot_file_read_tool")
+            )
 
         await agent_runner.reset(
             provider=prov,

astrbot/core/tools/computer_tools/fs.py

@@ -46,6 +46,7 @@
 from astrbot.core.message.components import File
 from astrbot.core.utils.astrbot_path import (
     get_astrbot_skills_path,
+    get_astrbot_system_tmp_path,
     get_astrbot_temp_path,
 )
 
@@ -71,7 +72,7 @@ def _restricted_env_path_labels(umo: str) -> list[str]:
     return [
         "data/skills",
         f"data/workspaces/{normalized_umo}",
-        "/tmp/.astrbot",
+        get_astrbot_system_tmp_path(),
     ]
 
 
@@ -91,7 +92,7 @@ def _read_allowed_roots(umo: str) -> tuple[Path, ...]:
     return (
         Path(get_astrbot_skills_path()).resolve(strict=False),
         _workspace_root(umo),
-        Path("/tmp/.astrbot").resolve(strict=False),
+        Path(get_astrbot_system_tmp_path()).resolve(strict=False),
     )