core/tools: embed truncate tokens in read_file (max_chars)

src/plyngent/tools/file/read.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from plyngent.agent import ToolTag, mark_lineno_read, tool
+from plyngent.tools.truncate_token import truncate_with_token
 from plyngent.tools.workspace import resolve_path
 
 _LINENO_WIDTH = 6
@@ -24,6 +25,7 @@ async def read_file(
     offset: int = 0,
     limit: int | None = None,
     with_lineno: bool = False,
+    max_chars: int | None = None,
 ) -> str:
     """Read a text file under the workspace.
 
@@ -31,6 +33,9 @@ async def read_file(
     When ``with_lineno`` is true, each line is prefixed with its 1-based file line
     number (``     N|…``), matching ``edit_lineno`` numbering, and those lines are
     marked readable for ``edit_lineno`` this turn.
+
+    ``max_chars`` caps the returned slice; a ``TRUNCATE_TOKEN`` is appended so
+    ``get_truncated`` can continue reading the rest without a new request.
     """
     target = resolve_path(path)
     if not target.is_file():
@@ -46,5 +51,18 @@ async def read_file(
     slice_lines = lines[start:end]
     if with_lineno:
         mark_lineno_read(str(target), set(range(start + 1, end + 1)))
-        return _format_with_lineno(slice_lines, start_lineno=start + 1)
-    return "".join(slice_lines)
+        out = _format_with_lineno(slice_lines, start_lineno=start + 1)
+    else:
+        out = "".join(slice_lines)
+    if max_chars is not None and max_chars >= 1:
+        char_start = len("".join(lines[:start]))
+        out, _ = truncate_with_token(
+            out,
+            max_chars,
+            kind="file",
+            location=path,  # arg form: short token, resolves to the same file
+            offset=char_start,
+            limit=max_chars,
+            total_len=len(text),
+        )
+    return out