Skip to content

Commit e42b672

Browse files
antsokclaude
andcommitted
Python: Render read_lines rows verbatim and drop the header
Review feedback on microsoft#7571. The header largely echoed the tool call, and the gutter already reveals the end of the file: an end_line past the end comes back with a lower last number, and omitting end_line reads to EOF by definition. The total line count added nothing the caller could not derive. Keeping each line's terminator instead of stripping it removes the need for a line-ending indicator altogether. Every row carries its own terminator, so a mixed-ending file needs no detection, and the text after the gutter can be reused as a file_access_replace_lines new_line without dropping a \r\n. The terminator doubles as the row separator. Drops _strip_line_terminator and _line_ending_style, and returns _slice_lines to a plain list now that the total is unused. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
1 parent a02ca70 commit e42b672

3 files changed

Lines changed: 45 additions & 57 deletions

File tree

‎python/packages/core/AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -124,7 +124,7 @@ agent_framework/
124124
- **`FileSystemAgentFileStore`** - Disk-backed store rooted under a configurable directory. Enforces relative-path normalization, root containment, and rejects symlink/reparse-point segments to prevent escape.
125125
- **`FileSearchResult`** / **`FileSearchMatch`** - `SerializationMixin` DTOs returned by `search`, carrying the matching file name, a context snippet, and the matching lines with 1-based line numbers.
126126
- **`FileStoreEntry`** - `SerializationMixin` DTO returned by `list_children`, carrying an entry `name` and `type` (`"file"` or `"directory"`).
127-
- **`FileAccessProvider`** - `ContextProvider` that adds shared file-access tools (`file_access_write`, `file_access_read`, `file_access_read_lines`, `file_access_delete`, `file_access_ls`, `file_access_grep`, `file_access_replace`, `file_access_replace_lines`) plus default usage instructions to each invocation. `file_access_ls` enumerates direct children (both files and subdirectories) as `{name, type}` entries with an optional `glob_pattern`, so the agent can walk the tree level by level; `file_access_grep` searches recursively from an optional base `directory` and returns relative `file_name` paths, scoped via an `fnmatch` `glob_pattern` (where `*` crosses `/`, e.g. `*.md`, `reports/*`). `file_access_replace` substitutes `old_string` with `new_string` (failing if not found, or if multiple matches and `replace_all` is false); `file_access_replace_lines` replaces whole 1-based lines with literal text (each `new_line` includes its own trailing newline; an empty `new_line` deletes the line, including its line break). `file_access_read_lines` returns a 1-based inclusive line range as numbered text prefixed by a header carrying the total line count and the file's line-ending style; `end_line` may be omitted to read to the end of the file, and an `end_line` past the last line clamps to it. Its line numbering comes from the same `_split_lines_keepends` split as `file_access_grep` and `file_access_replace_lines`, so a number reported by grep addresses the same line in all three tools, including the trailing empty line of a newline-terminated file. All tools are registered with `approval_mode="always_require"` by default, so every file operation needs host approval. Pass `disable_write_tools=True` to advertise only the read-only tools. To run unattended you can disable approval at the source with `disable_readonly_tool_approval=True` (read, read_lines, ls, grep) and/or `disable_write_tool_approval=True` (write, delete, replace, replace_lines), which register the affected tools with `approval_mode="never_require"`; alternatively, keep approval on and pass one of the static auto-approval rules to `ToolApprovalMiddleware` (via `auto_approval_rules`): `FileAccessProvider.read_only_tools_auto_approval_rule` approves only the read-only tools (read, read_lines, ls, grep), while `FileAccessProvider.all_tools_auto_approval_rule` approves every file-access tool including the write tools. Both rules reject any call carrying a `server_label` so they stay scoped to this provider's local tools and never auto-approve a same-named hosted tool. The tool names are also exposed as class constants (`WRITE_TOOL_NAME`, `READ_TOOL_NAME`, `READ_LINES_TOOL_NAME`, `DELETE_TOOL_NAME`, `LS_TOOL_NAME`, `GREP_TOOL_NAME`, `REPLACE_TOOL_NAME`, `REPLACE_LINES_TOOL_NAME`). Unlike `MemoryContextProvider`, the store is intentionally shared across sessions and agents.
127+
- **`FileAccessProvider`** - `ContextProvider` that adds shared file-access tools (`file_access_write`, `file_access_read`, `file_access_read_lines`, `file_access_delete`, `file_access_ls`, `file_access_grep`, `file_access_replace`, `file_access_replace_lines`) plus default usage instructions to each invocation. `file_access_ls` enumerates direct children (both files and subdirectories) as `{name, type}` entries with an optional `glob_pattern`, so the agent can walk the tree level by level; `file_access_grep` searches recursively from an optional base `directory` and returns relative `file_name` paths, scoped via an `fnmatch` `glob_pattern` (where `*` crosses `/`, e.g. `*.md`, `reports/*`). `file_access_replace` substitutes `old_string` with `new_string` (failing if not found, or if multiple matches and `replace_all` is false); `file_access_replace_lines` replaces whole 1-based lines with literal text (each `new_line` includes its own trailing newline; an empty `new_line` deletes the line, including its line break). `file_access_read_lines` returns a 1-based inclusive line range, one line per row as `<line_number>\t<line>`; `end_line` may be omitted to read to the end of the file, and an `end_line` past the last line clamps to it. Everything after the tab is verbatim, including the line's own terminator (which therefore doubles as the row separator), so a row's text can be fed straight back as a `file_access_replace_lines` `new_line` without losing a `\r\n`. Its line numbering comes from the same `_split_lines_keepends` split as `file_access_grep` and `file_access_replace_lines`, so a number reported by grep addresses the same line in all three tools, including the trailing empty line of a newline-terminated file. All tools are registered with `approval_mode="always_require"` by default, so every file operation needs host approval. Pass `disable_write_tools=True` to advertise only the read-only tools. To run unattended you can disable approval at the source with `disable_readonly_tool_approval=True` (read, read_lines, ls, grep) and/or `disable_write_tool_approval=True` (write, delete, replace, replace_lines), which register the affected tools with `approval_mode="never_require"`; alternatively, keep approval on and pass one of the static auto-approval rules to `ToolApprovalMiddleware` (via `auto_approval_rules`): `FileAccessProvider.read_only_tools_auto_approval_rule` approves only the read-only tools (read, read_lines, ls, grep), while `FileAccessProvider.all_tools_auto_approval_rule` approves every file-access tool including the write tools. Both rules reject any call carrying a `server_label` so they stay scoped to this provider's local tools and never auto-approve a same-named hosted tool. The tool names are also exposed as class constants (`WRITE_TOOL_NAME`, `READ_TOOL_NAME`, `READ_LINES_TOOL_NAME`, `DELETE_TOOL_NAME`, `LS_TOOL_NAME`, `GREP_TOOL_NAME`, `REPLACE_TOOL_NAME`, `REPLACE_LINES_TOOL_NAME`). Unlike `MemoryContextProvider`, the store is intentionally shared across sessions and agents.
128128

129129
### File Memory Harness (`_harness/_file_memory.py`)
130130

‎python/packages/core/agent_framework/_harness/_file_access.py‎

Lines changed: 7 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -287,8 +287,8 @@ def _line_edits(edits: list[Any]) -> list[tuple[int, str]]:
287287
return normalized
288288

289289

290-
def _slice_lines(content: str, start_line: int, end_line: int | None) -> tuple[list[str], int]:
291-
"""Return the 1-based inclusive ``[start_line, end_line]`` slice of ``content`` and its total line count.
290+
def _slice_lines(content: str, start_line: int, end_line: int | None) -> list[str]:
291+
"""Return the 1-based inclusive ``[start_line, end_line]`` slice of ``content``, terminators kept.
292292
293293
Uses :func:`_split_lines_keepends`, so a ``line_number`` from ``grep`` addresses the
294294
same line here and in ``replace_lines``, including the trailing empty line of a
@@ -310,21 +310,7 @@ def _slice_lines(content: str, start_line: int, end_line: int | None) -> tuple[l
310310
raise ValueError(f"end_line ({end_line}) must not be less than start_line ({start_line}).")
311311
if start_line > total:
312312
raise ValueError(f"start_line {start_line} is out of range (file has {total} lines).")
313-
return lines[start_line - 1 : total if end_line is None else min(end_line, total)], total
314-
315-
316-
def _strip_line_terminator(line: str) -> str:
317-
r"""Drop a keepends line's terminator, reproducing ``grep``'s ``rstrip("\r")`` rendering."""
318-
return line.removesuffix("\n").rstrip("\r")
319-
320-
321-
def _line_ending_style(content: str) -> str:
322-
"""Name ``content``'s line terminators, which reads strip but ``replace_lines`` takes literally."""
323-
crlf = content.count("\r\n")
324-
lf = content.count("\n") - crlf
325-
if crlf and lf:
326-
return "mixed LF/CRLF"
327-
return "CRLF" if crlf else "LF"
313+
return lines[start_line - 1 : total if end_line is None else min(end_line, total)]
328314

329315

330316
@experimental(feature_id=ExperimentalFeature.HARNESS)
@@ -1542,23 +1528,19 @@ async def file_access_read(file_name: str) -> str:
15421528
approval_mode=readonly_approval,
15431529
)
15441530
async def file_access_read_lines(file_name: str, start_line: int, end_line: int | None = None) -> str:
1545-
"""Read part of a file by 1-based inclusive line number; omit end_line to read to the end of the file, and an end_line past the last line is clamped. Line numbers match file_access_grep and file_access_replace_lines. Each line is prefixed with its number and a tab; that gutter is for reference only, never include it in a replacement line.""" # ruff:ignore[line-too-long]
1531+
"""Read part of a file by 1-based inclusive line number; omit end_line to read to the end of the file, and an end_line past the last line is clamped. Line numbers match file_access_grep and file_access_replace_lines. Each line is prefixed with its number and a tab; everything after that tab is verbatim, including the line's own terminator, so it can be reused as a file_access_replace_lines new_line.""" # ruff:ignore[line-too-long]
15461532
try:
15471533
normalized = _normalize_relative_path(file_name)
15481534
content = await self.store.read(normalized)
15491535
if content is None:
15501536
return f"File '{file_name}' not found."
1551-
sliced, total = _slice_lines(content, start_line, end_line)
1537+
sliced = _slice_lines(content, start_line, end_line)
15521538
except ValueError as exc:
15531539
return f"Could not read lines from file '{file_name}': {exc}"
15541540
except OSError as exc:
15551541
return f"Could not read lines from file '{file_name}': {exc.strerror or exc}"
1556-
header = (
1557-
f"Lines {start_line}-{start_line + len(sliced) - 1} of '{file_name}' "
1558-
f"({total} lines total, {_line_ending_style(content)} line endings):"
1559-
)
1560-
numbered = (f"{number}\t{_strip_line_terminator(line)}" for number, line in enumerate(sliced, start_line))
1561-
return "\n".join([header, *numbered])
1542+
# Each line keeps its terminator, so it doubles as the row separator.
1543+
return "".join(f"{number}\t{line}" for number, line in enumerate(sliced, start_line))
15621544

15631545
@tool(name=FileAccessProvider.DELETE_TOOL_NAME, schema=_DeleteFileInput, approval_mode=write_approval)
15641546
async def file_access_delete(file_name: str) -> str:

‎python/packages/core/tests/core/test_harness_file_access.py‎

Lines changed: 37 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -33,12 +33,10 @@
3333
from agent_framework._harness._file_access import (
3434
DEFAULT_FILE_ACCESS_INSTRUCTIONS,
3535
DEFAULT_FILE_ACCESS_SOURCE_ID,
36-
_line_ending_style,
3736
_matches_glob,
3837
_normalize_relative_path,
3938
_run_search_with_timeout,
4039
_slice_lines,
41-
_strip_line_terminator,
4240
)
4341

4442
from .conftest import create_junction_or_skip
@@ -1181,23 +1179,23 @@ async def current() -> str:
11811179
assert "Duplicate" in _text(dup[0])
11821180

11831181

1184-
def test_slice_lines_returns_inclusive_range_and_total() -> None:
1185-
"""``_slice_lines`` should slice 1-based inclusive ranges and report the keepends line count."""
1186-
assert _slice_lines("a\nb\nc\n", 1, 2) == (["a\n", "b\n"], 4)
1187-
assert _slice_lines("a\nb\nc\n", 2, 2) == (["b\n"], 4)
1182+
def test_slice_lines_returns_inclusive_range() -> None:
1183+
"""``_slice_lines`` should slice 1-based inclusive ranges with terminators kept."""
1184+
assert _slice_lines("a\nb\nc\n", 1, 2) == ["a\n", "b\n"]
1185+
assert _slice_lines("a\nb\nc\n", 2, 2) == ["b\n"]
11881186

11891187
# A trailing newline yields a final empty line that is in range, matching grep/replace_lines.
1190-
assert _slice_lines("a\nb\n", 1, None) == (["a\n", "b\n", ""], 3)
1191-
assert _slice_lines("a\nb\n", 3, 3) == ([""], 3)
1188+
assert _slice_lines("a\nb\n", 1, None) == ["a\n", "b\n", ""]
1189+
assert _slice_lines("a\nb\n", 3, 3) == [""]
11921190

11931191
# Empty content is a single empty line, not zero lines.
1194-
assert _slice_lines("", 1, None) == ([""], 1)
1192+
assert _slice_lines("", 1, None) == [""]
11951193

11961194
# An end_line past the last line clamps instead of failing.
11971195
assert _slice_lines("a\nb\n", 1, 99) == _slice_lines("a\nb\n", 1, None)
11981196

11991197
# Splitting on "\n" only leaves CRLF terminators attached.
1200-
assert _slice_lines("a\r\nb", 1, 1) == (["a\r\n"], 2)
1198+
assert _slice_lines("a\r\nb", 1, 1) == ["a\r\n"]
12011199

12021200

12031201
def test_slice_lines_rejects_invalid_ranges() -> None:
@@ -1212,19 +1210,6 @@ def test_slice_lines_rejects_invalid_ranges() -> None:
12121210
_slice_lines("a\nb\n", 99, None)
12131211

12141212

1215-
def test_line_rendering_helpers() -> None:
1216-
"""Displayed line text should match grep's, and the ending style should describe the file."""
1217-
assert _strip_line_terminator("a\r\n") == "a"
1218-
assert _strip_line_terminator("a\n") == "a"
1219-
assert _strip_line_terminator("a") == "a"
1220-
assert _strip_line_terminator("") == ""
1221-
1222-
assert _line_ending_style("a\nb\n") == "LF"
1223-
assert _line_ending_style("a\r\nb\r\n") == "CRLF"
1224-
assert _line_ending_style("a\r\nb\n") == "mixed LF/CRLF"
1225-
assert _line_ending_style("abc") == "LF"
1226-
1227-
12281213
async def test_file_access_read_lines(chat_client_base: SupportsChatGetResponse) -> None:
12291214
"""``file_access_read_lines`` should return a numbered range and report bad input as a message."""
12301215
tools = await _prepare_access_tools(chat_client_base)
@@ -1238,21 +1223,19 @@ async def read(**kwargs: object) -> str:
12381223
return _text((await read_lines.invoke(arguments={"file_name": "a.txt", **kwargs}))[0])
12391224

12401225
await write("one\ntwo\nthree\n")
1241-
header = "Lines {}-{} of 'a.txt' (4 lines total, LF line endings):"
1242-
assert await read(start_line=2, end_line=3) == f"{header.format(2, 3)}\n2\ttwo\n3\tthree"
1226+
assert await read(start_line=2, end_line=3) == "2\ttwo\n3\tthree\n"
12431227

12441228
# Omitting end_line reads to the end, including the trailing empty line.
1245-
assert await read(start_line=1) == f"{header.format(1, 4)}\n1\tone\n2\ttwo\n3\tthree\n4\t"
1229+
assert await read(start_line=1) == "1\tone\n2\ttwo\n3\tthree\n4\t"
12461230

12471231
# An end_line past the last line clamps rather than reporting an error.
12481232
clamped = await read(start_line=1, end_line=999)
12491233
assert clamped == await read(start_line=1)
12501234
assert "out of range" not in clamped
12511235

1252-
# CRLF terminators are stripped from the displayed text and named in the header.
1236+
# Each line keeps its own terminator, so a CRLF line can be reused verbatim.
12531237
await write("alpha\r\nbeta\r\n")
1254-
crlf_header = "Lines 1-1 of 'a.txt' (3 lines total, CRLF line endings):"
1255-
assert await read(start_line=1, end_line=1) == f"{crlf_header}\n1\talpha"
1238+
assert await read(start_line=1, end_line=1) == "1\talpha\r\n"
12561239

12571240
await write("one\ntwo\n")
12581241
for kwargs, expected in (
@@ -1285,8 +1268,10 @@ async def test_file_access_read_lines_shows_grep_line_numbers(
12851268

12861269
# Both blank lines grep reports are readable, including the trailing one.
12871270
for number in blanks:
1288-
shown = _text((await read_lines.invoke(arguments={"file_name": "a.txt", "start_line": number}))[0])
1289-
assert shown.splitlines()[1] == f"{number}\t"
1271+
shown = _text(
1272+
(await read_lines.invoke(arguments={"file_name": "a.txt", "start_line": number, "end_line": number}))[0]
1273+
)
1274+
assert shown.removeprefix(f"{number}\t") == ("\n" if number == 2 else "")
12901275

12911276
# The same number is then editable, closing the grep -> read -> edit loop.
12921277
edited = await replace_lines.invoke(
@@ -1296,6 +1281,27 @@ async def test_file_access_read_lines_shows_grep_line_numbers(
12961281
assert _text((await read.invoke(arguments={"file_name": "a.txt"}))[0]) == "a\n\nc\nd\n"
12971282

12981283

1284+
async def test_file_access_read_lines_round_trips_into_replace_lines(
1285+
chat_client_base: SupportsChatGetResponse,
1286+
) -> None:
1287+
"""The text after the gutter is literal, so a CRLF line survives a read-then-edit round trip."""
1288+
tools = await _prepare_access_tools(chat_client_base)
1289+
save = _tool_by_name(tools, "file_access_write")
1290+
read = _tool_by_name(tools, "file_access_read")
1291+
read_lines = _tool_by_name(tools, "file_access_read_lines")
1292+
replace_lines = _tool_by_name(tools, "file_access_replace_lines")
1293+
1294+
await save.invoke(arguments={"file_name": "a.txt", "content": "alpha\r\nbeta\r\n", "overwrite": True})
1295+
shown = _text((await read_lines.invoke(arguments={"file_name": "a.txt", "start_line": 2, "end_line": 2}))[0])
1296+
assert shown == "2\tbeta\r\n"
1297+
1298+
# Rewriting the line with the text it reported keeps the CRLF terminator intact.
1299+
await replace_lines.invoke(
1300+
arguments={"file_name": "a.txt", "edits": [{"line_number": 2, "new_line": shown.removeprefix("2\t").upper()}]}
1301+
)
1302+
assert _text((await read.invoke(arguments={"file_name": "a.txt"}))[0]) == "alpha\r\nBETA\r\n"
1303+
1304+
12991305
async def test_file_access_grep_line_numbers_are_editable(chat_client_base: SupportsChatGetResponse) -> None:
13001306
"""A ``line_number`` returned by ``file_access_grep`` must be in range for ``replace_lines``.
13011307

0 commit comments

Comments
 (0)