@@ -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-
15071389class _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 :
0 commit comments