Skip to content

Commit 92143fd

Browse files
antsokclaude
andcommitted
Python: Replace the runtime alignment check with a documented contract
From @westey-m's review, agreed by @eavanvalkenburg: documenting the expectation for implementers is preferable to checking at runtime, which costs every user to police implementations that are not per spec. A compliance test project is the better answer and is tracked separately. This mirrors the same removal in the .NET half of microsoft#7571. Gone: _verify_search_alignment, _numbers_are_trusted, _ALIGNED_STORE_TYPES, _MISALIGNED_SEARCH_MESSAGE, reports_aligned_line_numbers, and the disable_search_alignment_check option on both providers along with the memory provider's own refusal message. Fifteen tests went with them. The scan batching stays. _SCAN_BATCH_CHARS and the base search offload are a separate defence with their own measurements, and only verification's to_thread work is being removed here. The contract now lives on search(): an override must report line_number as a 1-based coordinate into split_lines of the same content read() returns, and should report the line verbatim, which scan_content does. Numbering against anything else fails silently -- the search looks right and the damage appears when a later edit lands on a line the caller never saw. Also from @westey-m's review on the .NET half, mirrored here: find_matching_files now says it narrows on both the glob and the regex rather than the regex alone, says why a store would override it (a name index for the glob, a content index for the regex), and documents that the glob is matched case-insensitively so a backend that cannot reproduce that must widen rather than narrow. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
1 parent 85ee6d2 commit 92143fd

4 files changed

Lines changed: 27 additions & 535 deletions

File tree

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

Lines changed: 26 additions & 164 deletions
Original file line numberDiff line numberDiff line change
@@ -265,7 +265,8 @@ def _split_lines_keepends(content: str) -> list[str]:
265265
:class:`AgentFileStore` implementations in this package, so for those stores a ``line_number``
266266
obtained from ``grep`` always targets the same line in the others and stays in range. A custom
267267
store supplies its own :meth:`AgentFileStore.search`, which must number by this split but does
268-
not inherit it, so the alignment does not follow automatically and the providers verify it.
268+
not inherit it; nothing checks that at runtime, so a store numbering differently edits the
269+
wrong line silently.
269270
270271
Splitting solely on ``\n`` (a trailing ``\r``
271272
stays attached to the line) means the result has ``len(content.split("\n"))``
@@ -683,19 +684,6 @@ async def file_exists(self, path: str) -> bool:
683684
path: The relative path of the file to check.
684685
"""
685686

686-
# Set to ``True`` by a store that overrides :meth:`search` and guarantees its
687-
# ``line_number`` values are coordinates in :meth:`split_lines` — normally because
688-
# it reports through :meth:`scan_content`. Declaring this opts the store out of the
689-
# alignment check :class:`FileAccessProvider` otherwise runs on every ``grep``,
690-
# which costs one extra read per *matched* file. Stores that do not override
691-
# :meth:`search` need not set it: the base implementation is aligned by
692-
# construction and is never checked.
693-
#
694-
# This is a promise, not a hint. Declaring it while numbering lines differently
695-
# reinstates exactly the failure the check exists to catch — ``replace_lines``
696-
# silently editing the wrong line — so only set it if a test pins the alignment.
697-
reports_aligned_line_numbers: ClassVar[bool] = False
698-
699687
@staticmethod
700688
def split_lines(content: str) -> list[str]:
701689
r"""Split ``content`` into the lines this store's line numbers address.
@@ -742,28 +730,36 @@ async def find_matching_files(
742730
*,
743731
recursive: bool = False,
744732
) -> list[str]:
745-
"""Return the names of files that **may** contain a match for ``regex_pattern``.
733+
"""Return the names of the files that **may** satisfy this search.
746734
747-
This is the hook a store uses to narrow the search to the files worth
748-
reading. Semantics are deliberately a **superset**:
735+
A candidate is a file whose content **may** contain text matching ``regex_pattern`` and
736+
whose name **may** match ``glob_pattern``. This is the hook a store uses to narrow the
737+
search to the files worth reading. Semantics are deliberately a **superset**:
749738
returning a file that turns out not to match is harmless — the base
750739
:meth:`search` re-scans every candidate and discards it — while omitting
751740
a file loses the match. A backend with a native search index should
752741
override this and push ``regex_pattern`` down to it, widening rather than
753742
guessing where the dialect cannot express the pattern.
754743
755744
The default implementation has no index to narrow with, so it walks :meth:`list_children`
756-
and returns every file in scope. Overriding :meth:`search` instead is also
757-
supported, but then line numbering is the store's responsibility (see
758-
:meth:`split_lines`) and :class:`FileAccessProvider` verifies it.
745+
and returns every file in scope, leaving :meth:`search` to read and scan all of them.
746+
Override this when the backing store can answer either question more cheaply than that —
747+
a name index for ``glob_pattern``, a content or full-text index for ``regex_pattern`` — and
748+
return the candidates it finds. That is the whole purpose of the hook: the store does the
749+
narrowing it is good at, and the base keeps the scanning and the line numbering. Overriding
750+
:meth:`search` instead is also supported, but then line numbering is the store's
751+
responsibility (see :meth:`split_lines`), and nothing checks it at runtime.
759752
760753
Args:
761754
directory: The relative directory to search. Use ``""`` for the root.
762755
regex_pattern: The pattern :meth:`search` was called with, as a hint. It is the bare
763756
source string: :meth:`search` compiles it **case-insensitively**, so an index
764757
queried case-sensitively with it will miss files and silently lose those matches.
765758
glob_pattern: The same optional glob :meth:`search` received, matched
766-
against each file's path relative to ``directory``.
759+
against each file's path relative to ``directory``, also
760+
**case-insensitively**. The same rule applies: widen rather than narrow when
761+
the backend cannot reproduce that, since returning only case-exact names
762+
drops files the caller would have got.
767763
768764
Keyword Args:
769765
recursive: When ``False`` (default) only direct children are in scope.
@@ -804,8 +800,15 @@ async def search(
804800
model-supplied regex runs in a worker thread.
805801
806802
Overriding this method is supported — a backend that can perform the
807-
whole search natively should — but the override then owns line numbering
808-
and must follow :meth:`split_lines`, typically via :meth:`scan_content`.
803+
whole search natively should — but the override then owns line numbering.
804+
An override must report ``line_number`` as a 1-based coordinate into
805+
:meth:`split_lines` of the same content :meth:`read` returns, and should
806+
report the matching line verbatim, terminator included;
807+
:meth:`scan_content` produces both correctly. Numbering against anything
808+
else is a bug with a silent failure mode: the search looks correct, and
809+
the damage appears later when a line edit applies to a line the caller
810+
never saw. Cover it with a test that greps and then edits by the reported
811+
number.
809812
810813
Args:
811814
directory: The relative directory to search. Use ``""`` for the root.
@@ -1383,127 +1386,6 @@ async def create_directory(self, path: str) -> None:
13831386
await asyncio.to_thread(lambda: full_path.mkdir(parents=True, exist_ok=True))
13841387

13851388

1386-
# Store types whose ``search`` numbers lines with :meth:`AgentFileStore.split_lines`. Matched by
1387-
# exact type rather than ``isinstance``: both scan their own storage instead of going through
1388-
# ``read``, so a subclass overriding only ``read`` would have grep and the line editor looking at
1389-
# different text while inheriting the trust. (The .NET port declares a property instead, which is
1390-
# safe there only because both of its shipped stores are sealed.)
1391-
_ALIGNED_STORE_TYPES: frozenset[type[AgentFileStore]] = frozenset({
1392-
InMemoryAgentFileStore,
1393-
FileSystemAgentFileStore,
1394-
})
1395-
1396-
1397-
def _numbers_are_trusted(store: AgentFileStore) -> bool:
1398-
"""Whether ``store``'s line numbers are known to be :meth:`AgentFileStore.split_lines` coordinates."""
1399-
if store.reports_aligned_line_numbers:
1400-
return True
1401-
# Both rules below read the class, so an instance attribute shadowing ``search`` would let
1402-
# the class-level identity vouch for a method that never runs.
1403-
instance_attributes = getattr(store, "__dict__", {})
1404-
if "search" in instance_attributes:
1405-
return False
1406-
# The base ``search`` numbers whatever ``self.read`` returns, which is the text the editor
1407-
# indexes, so it stays aligned however ``read`` is replaced, on the class or the instance.
1408-
if type(store).search is AgentFileStore.search:
1409-
return True
1410-
# The shipped stores scan their own storage instead of going through ``read``, so wrapping
1411-
# ``read`` on the instance leaves grep numbering text the editor never sees.
1412-
return type(store) in _ALIGNED_STORE_TYPES and "read" not in instance_attributes
1413-
1414-
1415-
_MISALIGNED_SEARCH_MESSAGE = (
1416-
"Could not search files: this store's line numbers do not line up with the numbering used by "
1417-
"file_access_read_lines and file_access_replace_lines, so editing by the reported numbers would "
1418-
"change the wrong lines (or a file changed while the search ran). Use file_access_read or "
1419-
"file_access_read_lines to locate the content before editing."
1420-
)
1421-
1422-
1423-
async def _verify_search_alignment(
1424-
store: AgentFileStore,
1425-
directory: str,
1426-
results: list[FileSearchResult],
1427-
regex_pattern: str,
1428-
message: str = _MISALIGNED_SEARCH_MESSAGE,
1429-
) -> str | None:
1430-
"""Check that a store's reported line numbers address the lines the editor will edit.
1431-
1432-
Skipped entirely when the store uses a ``search`` implementation already known to
1433-
be aligned. Otherwise every reported ``line_number`` is re-checked by running the
1434-
pattern against that line of :meth:`AgentFileStore.split_lines`, which is what
1435-
``replace_lines`` will index into. Matching by pattern rather than by string
1436-
equality is deliberate: a custom store is not required to report the line verbatim
1437-
with its terminator, so comparing text would reject correct stores.
1438-
1439-
This is detection, not proof — a pattern that matches every line (``.``) passes
1440-
even if the numbering is skewed — and it is deliberately whole-call: a single
1441-
skewed file means the store's coordinates cannot be trusted anywhere. A matched
1442-
file that cannot be read fails the call for the same reason, since its numbers
1443-
go unchecked; the message names a mid-search change as one of its causes.
1444-
1445-
Args:
1446-
store: The store whose numbers are being checked.
1447-
directory: The directory the search ran in.
1448-
results: The results to check.
1449-
regex_pattern: The pattern the search ran with.
1450-
message: Returned on a mismatch. The default names the file-access tools; the memory
1451-
provider passes its own, because it registers neither of them.
1452-
1453-
Returns:
1454-
``None`` when the numbers are trustworthy, otherwise a message for the model.
1455-
"""
1456-
if not results or _numbers_are_trusted(store):
1457-
return None
1458-
1459-
regex = _compile_search_regex(regex_pattern)
1460-
1461-
def check(scanned: list[tuple[FileSearchResult, str]]) -> bool:
1462-
for result, content in scanned:
1463-
lines = AgentFileStore.split_lines(content)
1464-
for match in result.matching_lines:
1465-
# Both bounds: 0 or negative would index from the end and could match, passing a
1466-
# store whose numbers the editor will reject.
1467-
if not 1 <= match.line_number <= len(lines):
1468-
return False
1469-
if regex.search(_strip_line_terminator(lines[match.line_number - 1])) is None:
1470-
return False
1471-
return True
1472-
1473-
async def verify() -> bool:
1474-
batch: list[tuple[FileSearchResult, str]] = []
1475-
batched_chars = 0
1476-
for result in results:
1477-
try:
1478-
content = await store.read(_combine_search_path(directory, result.file_name))
1479-
except (OSError, ValueError):
1480-
# Deleted, unreadable, or not UTF-8. Its numbers went unchecked, and the check
1481-
# is whole-call, so nothing here can be certified.
1482-
logger.warning("Unverifiable file during search check: %s", result.file_name)
1483-
return False
1484-
if content is None:
1485-
return False
1486-
batch.append((result, content))
1487-
batched_chars += len(content)
1488-
if batched_chars < _SCAN_BATCH_CHARS:
1489-
continue
1490-
# The model supplies this pattern, so it runs in a worker thread rather than on the
1491-
# loop. Discarding each batch bounds peak memory by the budget the scan already uses.
1492-
if not await asyncio.to_thread(check, batch):
1493-
return False
1494-
batch.clear()
1495-
batched_chars = 0
1496-
return not batch or await asyncio.to_thread(check, batch)
1497-
1498-
try:
1499-
# The bound covers the reads as well as the scan: on a remote store the reads dominate,
1500-
# and an unbounded verification pass would hang grep for as long as they take.
1501-
aligned = await asyncio.wait_for(verify(), timeout=_SEARCH_TIMEOUT_SECONDS)
1502-
except asyncio.TimeoutError:
1503-
return message
1504-
return None if aligned else message
1505-
1506-
15071389
class _WriteFileInput(BaseModel):
15081390
"""Input schema for ``file_access_write``."""
15091391

@@ -1740,7 +1622,6 @@ def __init__(
17401622
disable_write_tools: bool = False,
17411623
disable_readonly_tool_approval: bool = False,
17421624
disable_write_tool_approval: bool = False,
1743-
disable_search_alignment_check: bool = False,
17441625
) -> None:
17451626
"""Initialize the file access provider.
17461627
@@ -1767,26 +1648,13 @@ def __init__(
17671648
``file_access_replace``, ``file_access_replace_lines``) are
17681649
registered with ``approval_mode="never_require"`` so they run
17691650
without host approval. Defaults to ``False`` (approval required).
1770-
disable_search_alignment_check: When ``True``, ``file_access_grep`` skips the
1771-
check that a store's reported ``line_number`` values address the same
1772-
lines ``file_access_read_lines`` and ``file_access_replace_lines`` act
1773-
on. That check only runs for a store which overrides
1774-
:meth:`AgentFileStore.search` without declaring
1775-
:attr:`AgentFileStore.reports_aligned_line_numbers`, and costs one extra
1776-
read per *matched* file. Turn it off only when the store's alignment is
1777-
established some other way: without it, a mis-numbered grep result is
1778-
handed to the model and an edit can land on the wrong line silently.
1779-
Prefer setting ``reports_aligned_line_numbers`` on the store, which is
1780-
narrower — it opts out one store rather than every store this provider
1781-
is ever given. Defaults to ``False`` (the check runs).
17821651
"""
17831652
super().__init__(source_id)
17841653
self.store = store
17851654
self.instructions = instructions or DEFAULT_FILE_ACCESS_INSTRUCTIONS
17861655
self.disable_write_tools = disable_write_tools
17871656
self.disable_readonly_tool_approval = disable_readonly_tool_approval
17881657
self.disable_write_tool_approval = disable_write_tool_approval
1789-
self.disable_search_alignment_check = disable_search_alignment_check
17901658
# Serializes mutating tool operations (write/delete/replace/replace_lines).
17911659
# The provider is shared across sessions/agents, so read-modify-write tools
17921660
# (replace/replace_lines) could otherwise interleave and lose updates. Note
@@ -2045,12 +1913,6 @@ async def file_access_grep(
20451913
target = directory if directory and directory.strip() else ""
20461914
try:
20471915
results = await self.store.search(target, regex_pattern, glob_filter, recursive=True)
2048-
if not self.disable_search_alignment_check:
2049-
# Inside the same guard: the check compiles the pattern itself, so a store that
2050-
# accepts one this package would reject must not throw out of the tool.
2051-
misaligned = await _verify_search_alignment(self.store, target, results, regex_pattern)
2052-
if misaligned is not None:
2053-
return misaligned
20541916
except ValueError as exc:
20551917
return f"Could not search files: {exc}"
20561918
except OSError as exc:

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

Lines changed: 0 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,6 @@
5151
_line_edits, # pyright: ignore[reportPrivateUsage]
5252
_matches_glob, # pyright: ignore[reportPrivateUsage]
5353
_normalize_relative_path, # pyright: ignore[reportPrivateUsage]
54-
_verify_search_alignment, # pyright: ignore[reportPrivateUsage]
5554
)
5655

5756
logger = logging.getLogger(__name__)
@@ -74,14 +73,6 @@
7473
"compacted or truncated. This ensures important data remains accessible across long-running sessions."
7574
)
7675

77-
# The file-access wording names tools this provider does not register: there is no
78-
# ``file_memory_read_lines``, so the model is pointed at ``file_memory_read`` instead.
79-
_MISALIGNED_MEMORY_SEARCH_MESSAGE = (
80-
"Could not search memory files: this store's line numbers do not line up with the numbering "
81-
"used by file_memory_replace_lines, so editing by the reported numbers would change the wrong "
82-
"lines (or a file changed while the search ran). Use file_memory_read to locate the content "
83-
"before editing."
84-
)
8576

8677
_DESCRIPTION_SUFFIX = "_description.md"
8778
_MEMORY_INDEX_FILE_NAME = "memories.md"
@@ -265,7 +256,6 @@ def __init__(
265256
source_id: str = DEFAULT_FILE_MEMORY_SOURCE_ID,
266257
scope: str | None = None,
267258
instructions: str | None = None,
268-
disable_search_alignment_check: bool = False,
269259
) -> None:
270260
"""Initialize the file memory provider.
271261
@@ -280,20 +270,11 @@ def __init__(
280270
``session_id`` is used, isolating memories per session.
281271
instructions: Optional instruction override. When ``None`` the
282272
default file-memory instructions are used.
283-
disable_search_alignment_check: When ``True``, ``file_memory_grep`` skips the
284-
check that a store's reported ``line_number`` values address the same
285-
lines ``file_memory_replace_lines`` acts on. See the same argument on
286-
:class:`~agent_framework.FileAccessProvider`; prefer declaring
287-
:attr:`AgentFileStore.reports_aligned_line_numbers` on the store instead.
288-
Weigh it more carefully here: these tools are registered
289-
``approval_mode="never_require"``, so a wrong-line edit is applied with
290-
no host approval. Defaults to ``False`` (the check runs).
291273
"""
292274
super().__init__(source_id)
293275
self.store = store
294276
self.scope = scope
295277
self.instructions = instructions or DEFAULT_FILE_MEMORY_INSTRUCTIONS
296-
self.disable_search_alignment_check = disable_search_alignment_check
297278
# Serializes write/delete operations (and their index rebuilds) so the
298279
# ``memories.md`` index stays consistent. A single per-instance lock is
299280
# sufficient for v1; concurrent writes across scopes are rare in practice.
@@ -513,14 +494,6 @@ async def file_memory_grep(
513494
# Drop the internal files first: the index and the description sidecars are never
514495
# shown to the agent, so a match inside one must not refuse the whole grep.
515496
visible = [result for result in results if not _is_internal_file(result.file_name)]
516-
if not self.disable_search_alignment_check:
517-
# Inside the same guard: the check compiles the pattern itself, so a store that
518-
# accepts one this package would reject must not throw out of the tool.
519-
misaligned = await _verify_search_alignment(
520-
self.store, working_folder, visible, regex_pattern, _MISALIGNED_MEMORY_SEARCH_MESSAGE
521-
)
522-
if misaligned is not None:
523-
return misaligned
524497
except ValueError as exc:
525498
return f"Could not search memory files: {exc}"
526499
except OSError as exc:

0 commit comments

Comments
 (0)