fix(sdk): explain truncation markers only when preview omits lines

Author: mdrxy

libs/deepagents/deepagents/backends/utils.py

@@ -24,6 +24,17 @@
 MAX_VIDEO_INPUT_BYTES: Final = 1024 * 1024 * 1024
 """Maximum raw video payload size accepted by `read_file` frame extraction."""
 
+TRUNCATION_MARKER_TEMPLATE: Final = "... [{omitted_lines} lines truncated] ..."
+"""Marker standing in for lines dropped from the middle of a head/tail preview.
+
+Shared by `_message_eviction._create_content_preview` and the capture wrapper
+in `backends.sandbox` so both emit identical marker text.
+
+Never scan preview text for this marker to detect truncation: output can
+contain a literal marker line. Producers report marker presence out of band
+instead (see `ExecuteOffloadResult.preview_has_truncation_marker`).
+"""
+
 FileType = Literal["text", "image", "audio", "video", "file"]
 """Classification of a file by extension."""
 

libs/deepagents/deepagents/middleware/_message_eviction.py

@@ -11,56 +11,129 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, cast
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Final, cast
 
 from langchain_core.messages import BaseMessage, ToolMessage
 
-from deepagents.backends.utils import format_content_with_line_numbers, sanitize_tool_call_id
+from deepagents.backends.utils import (
+    TRUNCATION_MARKER_TEMPLATE,
+    format_content_with_line_numbers,
+    sanitize_tool_call_id,
+)
 
 if TYPE_CHECKING:
     from langchain_core.messages.content import ContentBlock
 
     from deepagents.backends.protocol import BackendProtocol
 
-TOO_LARGE_TOOL_MSG = """Tool result too large, the result of this tool call {tool_call_id} was saved in the filesystem at this path: {file_path}
+_TOO_LARGE_TOOL_MSG = """Tool result too large, the result of this tool call {tool_call_id} was saved in the filesystem at this path: {file_path}
 
 You can read the result from the filesystem by using the read_file tool, but make sure to only read part of the result at a time.
 
 You can do this by specifying an offset and limit in the read_file tool call. For example, to read the first 100 lines, you can use the read_file tool with offset=0 and limit=100.
 
-Here is a preview showing the head and tail of the result (lines of the form `... [N lines truncated] ...` indicate omitted lines in the middle of the content):
+{preview_note}
 
 {content_sample}
 """
 
+_PREVIEW_LINE_CHAR_LIMIT: Final = 1000
+"""Per-line character budget for preview lines.
 
-def _create_content_preview(content_str: str, *, head_lines: int = 5, tail_lines: int = 5) -> str:
-    """Create a preview of content showing head and tail with truncation marker.
+Bounds previews of few-but-huge lines (a `.jsonl` dump, a minified bundle).
+Keep below `backends.utils.MAX_LINE_LENGTH`, or clipped lines also pick up
+that renderer's `N.1` continuation gutters.
+"""
+
+_PREVIEW_NOTE_PLAIN = "Here is a preview of the {subject}"
+_PREVIEW_NOTE_HEAD_TAIL = "Here is a preview showing the head and tail of the {subject}"
+
+_CAVEAT_OMITTED_LINES = (
+    f"lines of the form `{TRUNCATION_MARKER_TEMPLATE.format(omitted_lines='N')}` indicate omitted lines in the middle of the content"
+)
+
+
+@dataclass(frozen=True, slots=True)
+class ContentPreview:
+    """A rendered preview plus a record of what was left out to build it.
+
+    `lines_omitted` is reported by the code that built `text`, never inferred
+    from the rendered bytes — a literal `... [N lines truncated] ...` line in
+    the content would otherwise pass for a real marker.
+    """
+
+    text: str
+    """The rendered, line-numbered preview."""
+
+    lines_omitted: bool
+    """Whole lines were dropped from the middle, behind a truncation marker."""
+
+
+def _preview_note(*, lines_omitted: bool, subject: str = "result") -> str:
+    """Build the sentence introducing a preview.
+
+    Explains the truncation marker only when the preview actually has one, so
+    the model is never told to look for a marker that was not inserted.
+
+    Args:
+        lines_omitted: Whole lines were dropped from the middle behind a
+            truncation marker.
+        subject: Noun for what is being previewed, e.g. `result`.
+
+    Returns:
+        The note, ending in a colon.
+
+            For example:
+
+            - `lines_omitted=False`: `Here is a preview of the result:`
+            - `lines_omitted=True`: `Here is a preview showing the head and tail
+                of the result (lines of the form ... indicate omitted lines ...):`
+    """
+    base = _PREVIEW_NOTE_HEAD_TAIL if lines_omitted else _PREVIEW_NOTE_PLAIN
+    note = base.format(subject=subject)
+    if lines_omitted:
+        note += f" ({_CAVEAT_OMITTED_LINES})"
+    return f"{note}:"
+
+
+def _create_content_preview(content_str: str, *, head_lines: int = 5, tail_lines: int = 5) -> ContentPreview:
+    """Create a line-numbered preview of `content_str`.
+
+    Shows all lines when they fit within `head_lines + tail_lines`, otherwise
+    the head and tail around a `... [N lines truncated] ...` marker.
 
     Args:
         content_str: The full content string to preview.
         head_lines: Number of lines to show from the start.
         tail_lines: Number of lines to show from the end.
 
     Returns:
-        Formatted preview string with line numbers.
+        The formatted preview plus a record of what was left out to build it.
     """
     lines = content_str.splitlines()
 
     if len(lines) <= head_lines + tail_lines:
         # If file is small enough, show all lines
-        preview_lines = [line[:1000] for line in lines]
-        return format_content_with_line_numbers(preview_lines, start_line=1)
+        preview_lines = [line[:_PREVIEW_LINE_CHAR_LIMIT] for line in lines]
+        return ContentPreview(
+            format_content_with_line_numbers(preview_lines, start_line=1),
+            lines_omitted=False,
+        )
 
     # Show head and tail with truncation marker
-    head = [line[:1000] for line in lines[:head_lines]]
-    tail = [line[:1000] for line in lines[-tail_lines:]]
+    head = [line[:_PREVIEW_LINE_CHAR_LIMIT] for line in lines[:head_lines]]
+    tail = [line[:_PREVIEW_LINE_CHAR_LIMIT] for line in lines[-tail_lines:]]
 
     head_sample = format_content_with_line_numbers(head, start_line=1)
-    truncation_notice = f"\n... [{len(lines) - head_lines - tail_lines} lines truncated] ...\n"
+    marker = TRUNCATION_MARKER_TEMPLATE.format(omitted_lines=len(lines) - head_lines - tail_lines)
+    truncation_notice = f"\n{marker}\n"
     tail_sample = format_content_with_line_numbers(tail, start_line=len(lines) - tail_lines + 1)
 
-    return head_sample + truncation_notice + tail_sample
+    return ContentPreview(
+        head_sample + truncation_notice + tail_sample,
+        lines_omitted=True,
+    )
 
 
 def _extract_text_from_message(message: BaseMessage) -> str:
@@ -116,6 +189,48 @@ def _build_evicted_tool_message(message: ToolMessage, evicted_content: str | lis
     )
 
 
+def _render_preview_stub(template: str, preview: ContentPreview, *, subject: str = "result", **fields: str) -> str:
+    """Render `template` around `preview`, deriving the note from that same preview.
+
+    The only way to fill a `{preview_note}`/`{content_sample}` template, so the
+    note cannot end up describing losses some other preview had.
+
+    Args:
+        template: Stub text with `{preview_note}` and `{content_sample}`
+            placeholders, plus whatever `fields` supplies.
+        preview: The preview to render and to derive the note from.
+        subject: Noun for what is being previewed, e.g. `result`.
+        fields: Remaining template placeholders, e.g. `file_path`.
+
+    Returns:
+        The rendered stub, ready to use as message content.
+    """
+    return template.format(
+        preview_note=_preview_note(lines_omitted=preview.lines_omitted, subject=subject),
+        content_sample=preview.text,
+        **fields,
+    )
+
+
+def _render_too_large_tool_msg(*, tool_call_id: str, file_path: str, content_str: str) -> str:
+    """Render the large-tool-result stub for `content_str`.
+
+    Args:
+        tool_call_id: Tool call whose result was offloaded.
+        file_path: Path the full content was written to.
+        content_str: The full content being previewed.
+
+    Returns:
+        The rendered stub, ready to use as message content.
+    """
+    return _render_preview_stub(
+        _TOO_LARGE_TOOL_MSG,
+        _create_content_preview(content_str),
+        tool_call_id=tool_call_id,
+        file_path=file_path,
+    )
+
+
 def _offload_tool_message_content(
     message: ToolMessage,
     content_str: str,
@@ -125,7 +240,7 @@ def _offload_tool_message_content(
     """Write `content_str` to `{prefix}/{tool_call_id}` and return a clipped replacement.
 
     The replacement carries a head+tail preview and the offload path in
-    `TOO_LARGE_TOOL_MSG` format so the agent can `read_file` the full content
+    large-tool-result format so the agent can `read_file` the full content
     by tool_call_id. Returns `None` if the backend write fails — caller should
     keep the original message in that case.
     """
@@ -134,11 +249,7 @@ def _offload_tool_message_content(
     result = backend.write(file_path, content_str)
     if result is None or result.error:
         return None
-    replacement_text = TOO_LARGE_TOOL_MSG.format(
-        tool_call_id=message.tool_call_id,
-        file_path=file_path,
-        content_sample=_create_content_preview(content_str),
-    )
+    replacement_text = _render_too_large_tool_msg(tool_call_id=message.tool_call_id, file_path=file_path, content_str=content_str)
     return _build_evicted_tool_message(message, _build_evicted_content(message, replacement_text))
 
 
@@ -154,9 +265,5 @@ async def _aoffload_tool_message_content(
     result = await backend.awrite(file_path, content_str)
     if result is None or result.error:
         return None
-    replacement_text = TOO_LARGE_TOOL_MSG.format(
-        tool_call_id=message.tool_call_id,
-        file_path=file_path,
-        content_sample=_create_content_preview(content_str),
-    )
+    replacement_text = _render_too_large_tool_msg(tool_call_id=message.tool_call_id, file_path=file_path, content_str=content_str)
     return _build_evicted_tool_message(message, _build_evicted_content(message, replacement_text))

libs/deepagents/deepagents/middleware/_overflow_clip.py

@@ -10,7 +10,7 @@
     is needed because the original file already lives at that path.
 - Any other tool result: full offload to `/large_tool_results/{tool_call_id}`
     via the shared eviction helper, then replace the message with a
-    `TOO_LARGE_TOOL_MSG` stub.
+    large-tool-result stub.
 """
 
 from __future__ import annotations

libs/deepagents/deepagents/middleware/filesystem.py

@@ -77,11 +77,13 @@
     validate_path,
 )
 from deepagents.middleware._message_eviction import (
-    TOO_LARGE_TOOL_MSG as TOO_LARGE_TOOL_MSG,
+    _TOO_LARGE_TOOL_MSG,
+    ContentPreview,
     _aoffload_tool_message_content,
     _create_content_preview,
     _extract_text_from_message,
     _offload_tool_message_content,
+    _render_preview_stub,
 )
 from deepagents.middleware._utils import append_to_system_message
 from deepagents.middleware._video import (
@@ -1485,11 +1487,11 @@ def supports_execution(backend: BackendProtocol) -> bool:
 )
 
 
-TOO_LARGE_HUMAN_MSG = """Message content too large and was saved to the filesystem at: {file_path}
+_TOO_LARGE_HUMAN_MSG = """Message content too large and was saved to the filesystem at: {file_path}
 
 You can read the full content using the read_file tool with pagination (offset and limit parameters).
 
-Here is a preview showing the head and tail of the content:
+{preview_note}
 
 {content_sample}
 """
@@ -1535,10 +1537,11 @@ def _build_truncated_human_message(message: HumanMessage, file_path: str) -> Hum
         A new HumanMessage with truncated content and the same `id`.
     """
     content_str = _extract_text_from_message(message)
-    content_sample = _create_content_preview(content_str)
-    replacement_text = TOO_LARGE_HUMAN_MSG.format(
+    replacement_text = _render_preview_stub(
+        _TOO_LARGE_HUMAN_MSG,
+        _create_content_preview(content_str),
+        subject="content",
         file_path=file_path,
-        content_sample=content_sample,
     )
     evicted = _build_evicted_human_content(message, replacement_text)
     return message.model_copy(update={"content": evicted})
@@ -2803,10 +2806,11 @@ def _interpret_capture_output(self, offload: ExecuteOffloadResult, capture_path:
         if response.truncated:
             status_line += "\n[Output exceeded the capture size limit and was truncated; the saved file is incomplete]"
         content_sample = f"{status_line}\n{response.output}"
-        return TOO_LARGE_TOOL_MSG.format(
+        return _render_preview_stub(
+            _TOO_LARGE_TOOL_MSG,
+            ContentPreview(content_sample, lines_omitted="lines truncated" in response.output),
             tool_call_id=tool_call_id,
             file_path=capture_path,
-            content_sample=content_sample,
         )
 
     def _create_execute_tool(self) -> BaseTool:  # noqa: C901

libs/deepagents/tests/unit_tests/test_end_to_end.py

@@ -4340,7 +4340,7 @@ def test_summarization_clips_ls_batch_on_overflow() -> None:
     `ls` isn't read_file, so the tail-clip path falls through to
     `_offload_tool_message_content`: full content written under
     `/large_tool_results/{tcid}` and the message replaced with a
-    `TOO_LARGE_TOOL_MSG` stub.
+    large-tool-result stub.
     """
     fake_model = _OverflowOnLargeInputModel(messages=iter([AIMessage(content="summary text"), AIMessage(content="final response")]))
     fake_model.call_history = []