Skip to content

Commit 72a1f03

Browse files
antsokclaude
andcommitted
.NET: Replace the runtime alignment check with a documented contract
From @westey-m's review. Policing implementations that are not per spec is not worth the cost at runtime; the expectation belongs on the type an implementer is reading when they get it wrong. A conformance test library, which is the real answer for checking an implementation, is tracked separately as microsoft#7931. SearchAlignment and BaseSearchResults are deleted, along with ReportsAlignedLineNumbers and its two overrides and DisableSearchAlignmentCheck on both provider options. SearchAsync returns its results directly instead of a tagged list, and neither provider verifies what a store reports. The contract those types enforced now sits on SearchAsync itself: a store overriding it must number FileSearchMatch.LineNumber as a 1-based coordinate into SplitLines of the content ReadAsync returns, ScanContent builds that correctly, and numbering against anything else is a bug whose failure mode is silent -- the search looks right, and the damage appears when a later line edit applies to a line the caller never saw. Two doc comments elsewhere still said the tools verify the numbering, which is no longer true of either. The FileSearchMatch and FileEditor remarks also scoped the rule to the stores shipped here rather than stating what implementers owe; both now read as expectations, which the same review asked for. Descriptions that state the line-counting rule now also say the numbers are 1-based, so a model counting lines from a whole-file read knows where to start. Eight tests went with the check: seven alignment cases and their six helper stores in AgentFileStoreContractTests, and the memory-refusal test with its skewed store in FileMemoryProviderTests. Nothing exercised the removed types otherwise; the remaining 2099 unit tests pass. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
1 parent acabb57 commit 72a1f03

13 files changed

Lines changed: 31 additions & 585 deletions

File tree

‎dotnet/src/Microsoft.Agents.AI/Harness/FileAccess/FileAccessProvider.cs‎

Lines changed: 5 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -147,7 +147,6 @@ first is rarely necessary.
147147
private readonly bool _disableWriteTools;
148148
private readonly bool _disableReadOnlyToolApproval;
149149
private readonly bool _disableWriteToolApproval;
150-
private readonly bool _disableSearchAlignmentCheck;
151150
private readonly SemaphoreSlim _writeLock = new(1, 1);
152151
private AITool[]? _tools;
153152

@@ -169,7 +168,6 @@ public FileAccessProvider(AgentFileStore fileStore, FileAccessProviderOptions? o
169168
this._disableWriteTools = options?.DisableWriteTools ?? false;
170169
this._disableReadOnlyToolApproval = options?.DisableReadOnlyToolApproval ?? false;
171170
this._disableWriteToolApproval = options?.DisableWriteToolApproval ?? false;
172-
this._disableSearchAlignmentCheck = options?.DisableSearchAlignmentCheck ?? false;
173171
}
174172

175173
/// <summary>
@@ -304,7 +302,7 @@ private async Task<string> WriteAsync(string fileName, string content, bool over
304302
/// <param name="fileName">The name of the file to read.</param>
305303
/// <param name="cancellationToken">A token to cancel the operation.</param>
306304
/// <returns>The file content or a not-found message.</returns>
307-
[Description("Read the content of a file by name. Returns the file content or a message indicating the file was not found. To edit by line number afterwards, count lines terminated by \\n, \\r\\n, or a lone \\r; each line keeps its own terminator, and content ending in a terminator has no extra empty line after it.")]
305+
[Description("Read the content of a file by name. Returns the file content or a message indicating the file was not found. To edit by 1-based line number afterwards, count lines terminated by \\n, \\r\\n, or a lone \\r; each line keeps its own terminator, and content ending in a terminator has no extra empty line after it.")]
308306
private async Task<string> ReadAsync(string fileName, CancellationToken cancellationToken = default)
309307
{
310308
string path = StorePaths.NormalizeRelativePath(fileName);
@@ -324,13 +322,13 @@ private async Task<string> ReadAsync(string fileName, CancellationToken cancella
324322
/// The line numbers agree with the ones <c>file_access_grep</c> reports, because
325323
/// <see cref="AgentFileStore.SearchAsync"/> must number by <see cref="AgentFileStore.SplitLines"/> —
326324
/// the split this method and <c>file_access_replace_lines</c> use. A store overriding it owns that
327-
/// numbering, so <c>file_access_grep</c> verifies it and refuses results that do not line up.
325+
/// numbering; getting it wrong makes an edit land on a line the caller never saw.
328326
/// </remarks>
329327
/// <exception cref="ArgumentException">
330328
/// Thrown when either bound is not positive, when <paramref name="endLine"/> precedes
331329
/// <paramref name="startLine"/>, or when <paramref name="startLine"/> is past the last line.
332330
/// </exception>
333-
[Description("Read part of a file by 1-based inclusive line number; omit endLine to read to the end of the file, and an endLine past the last line is clamped. 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. Line numbers count lines terminated by \\n, \\r\\n, or a lone \\r, and content ending in a terminator has no extra empty line after it.")]
331+
[Description("Read part of a file by 1-based inclusive line number; omit endLine to read to the end of the file, and an endLine past the last line is clamped. 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. Line numbers are 1-based and count lines terminated by \\n, \\r\\n, or a lone \\r, and content ending in a terminator has no extra empty line after it.")]
334332
private async Task<string> ReadLinesAsync(string fileName, int startLine, int? endLine = null, CancellationToken cancellationToken = default)
335333
{
336334
string path = StorePaths.NormalizeRelativePath(fileName);
@@ -433,7 +431,7 @@ private async Task<string> ReplaceAsync(string fileName, string oldString, strin
433431
/// <param name="edits">The list of 1-based line numbers and their literal replacement text.</param>
434432
/// <param name="cancellationToken">A token to cancel the operation.</param>
435433
/// <returns>A confirmation message including the number of lines replaced, or a failure message.</returns>
436-
[Description("Replace lines in a file. Provide a list of edits, each with a 1-based line_number and a literal new_line (include your own trailing newline); an empty new_line deletes the line, including its line break. Fails on out-of-range or duplicate line numbers. Line numbers count lines terminated by \\n, \\r\\n, or a lone \\r; each line keeps its own terminator, and content ending in a terminator has no extra empty line after it.")]
434+
[Description("Replace lines in a file. Provide a list of edits, each with a 1-based line_number and a literal new_line (include your own trailing newline); an empty new_line deletes the line, including its line break. Fails on out-of-range or duplicate line numbers. Line numbers are 1-based and count lines terminated by \\n, \\r\\n, or a lone \\r; each line keeps its own terminator, and content ending in a terminator has no extra empty line after it.")]
437435
private async Task<string> ReplaceLinesAsync(string fileName, List<FileLineEdit> edits, CancellationToken cancellationToken = default)
438436
{
439437
await this._writeLock.WaitAsync(cancellationToken).ConfigureAwait(false);
@@ -473,19 +471,14 @@ private async Task<string> ReplaceLinesAsync(string fileName, List<FileLineEdit>
473471
- '**' matches across subdirectories, so use \"**/*.md\" to match markdown files at any depth, or \"reports/**\" to restrict the search to the 'reports' subtree.
474472
475473
Returns matching results whose file names are paths relative to the store root (usable with file_access_read), along with snippets and matching lines with line numbers.
476-
Line numbers count lines terminated by \n, \r\n, or a lone \r, and content ending in a terminator has no extra empty line after it.
474+
Line numbers are 1-based and count lines terminated by \n, \r\n, or a lone \r, and content ending in a terminator has no extra empty line after it.
477475
""")]
478476
private async Task<List<FileSearchResult>> GrepAsync(string regexPattern, string? globPattern = null, string? directory = null, CancellationToken cancellationToken = default)
479477
{
480478
string? pattern = string.IsNullOrWhiteSpace(globPattern) ? null : globPattern;
481479
string target = StorePaths.NormalizeRelativePath(directory ?? string.Empty, isDirectory: true);
482480
IReadOnlyList<FileSearchResult> results = await this._fileStore.SearchAsync(target, regexPattern, pattern, recursive: true, cancellationToken).ConfigureAwait(false);
483481

484-
if (!this._disableSearchAlignmentCheck)
485-
{
486-
await SearchAlignment.ThrowIfMisalignedAsync(this._fileStore, target, results, regexPattern, cancellationToken).ConfigureAwait(false);
487-
}
488-
489482
// store.SearchAsync returns FileName relative to the searched directory; re-root each result to the
490483
// store root so the names compose directly with file_access_read/replace/delete.
491484
string prefix = target;

‎dotnet/src/Microsoft.Agents.AI/Harness/FileAccess/FileAccessProviderOptions.cs‎

Lines changed: 0 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -59,18 +59,4 @@ public sealed class FileAccessProviderOptions
5959
/// tools that modify the store are not exposed in that case.
6060
/// </remarks>
6161
public bool DisableWriteToolApproval { get; set; }
62-
63-
/// <summary>
64-
/// Gets or sets a value indicating whether to skip the check that a store's reported
65-
/// <see cref="FileSearchMatch.LineNumber"/> values address the same lines the line editor acts on.
66-
/// </summary>
67-
/// <remarks>
68-
/// The check only runs for a store that overrides <see cref="AgentFileStore.SearchAsync"/> without
69-
/// declaring <see cref="AgentFileStore.ReportsAlignedLineNumbers"/>, and costs one extra read per
70-
/// <em>matched</em> file. Turn it off only when the store's alignment is established some other
71-
/// way: without it, a mis-numbered grep result reaches the model and an edit can land on the wrong
72-
/// line silently. Prefer setting <see cref="AgentFileStore.ReportsAlignedLineNumbers"/> on the
73-
/// store, which opts out one store rather than every store this provider is given.
74-
/// </remarks>
75-
public bool DisableSearchAlignmentCheck { get; set; }
7662
}

‎dotnet/src/Microsoft.Agents.AI/Harness/FileMemory/FileMemoryProvider.cs‎

Lines changed: 2 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -62,12 +62,6 @@ public sealed class FileMemoryProvider : AIContextProvider, IDisposable
6262
/// <summary>The name of the tool that replaces whole lines within a memory file.</summary>
6363
public const string ReplaceLinesToolName = "file_memory_replace_lines";
6464

65-
// The file-access wording sends the model to read_lines, which this provider does not register.
66-
private const string MisalignedMemoryMessage =
67-
"This store's line numbers do not line up with the numbering used by file_memory_replace_lines, " +
68-
"so editing by the reported numbers would change the wrong lines (or a file changed while the " +
69-
"search ran). Use file_memory_read to locate the content before editing.";
70-
7165
private const string DescriptionSuffix = "_description.md";
7266
private const string MemoryIndexFileName = "memories.md";
7367
private const int MaxIndexEntries = 50;
@@ -93,7 +87,6 @@ This ensures important data remains accessible across long-running sessions.
9387
private readonly ProviderSessionState<FileMemoryState> _sessionState;
9488
private readonly SemaphoreSlim _writeLock = new(1, 1);
9589
private readonly string _instructions;
96-
private readonly bool _disableSearchAlignmentCheck;
9790
private IReadOnlyList<string>? _stateKeys;
9891
private AITool[]? _tools;
9992

@@ -114,7 +107,6 @@ public FileMemoryProvider(AgentFileStore fileStore, Func<AgentSession?, FileMemo
114107

115108
this._fileStore = fileStore;
116109
this._instructions = options?.Instructions ?? DefaultInstructions;
117-
this._disableSearchAlignmentCheck = options?.DisableSearchAlignmentCheck ?? false;
118110
this._sessionState = new ProviderSessionState<FileMemoryState>(
119111
stateInitializer ?? (_ => new FileMemoryState()),
120112
this.GetType().Name,
@@ -223,7 +215,7 @@ private async Task<string> WriteAsync(string fileName, string content, string? d
223215
/// <param name="fileName">The name of the file to read.</param>
224216
/// <param name="cancellationToken">A token to cancel the operation.</param>
225217
/// <returns>The file content or a not-found message.</returns>
226-
[Description("Read the content of a memory file by name. Returns the file content or a message indicating the file was not found. To edit by line number afterwards, count lines terminated by \\n, \\r\\n, or a lone \\r; each line keeps its own terminator, and content ending in a terminator has no extra empty line after it.")]
218+
[Description("Read the content of a memory file by name. Returns the file content or a message indicating the file was not found. To edit by 1-based line number afterwards, count lines terminated by \\n, \\r\\n, or a lone \\r; each line keeps its own terminator, and content ending in a terminator has no extra empty line after it.")]
227219
private async Task<string> ReadAsync(string fileName, CancellationToken cancellationToken = default)
228220
{
229221
string normalized = StorePaths.NormalizeRelativePath(fileName);
@@ -364,7 +356,7 @@ private async Task<string> ReplaceAsync(string fileName, string oldString, strin
364356
/// <param name="edits">The list of 1-based line numbers and their literal replacement text.</param>
365357
/// <param name="cancellationToken">A token to cancel the operation.</param>
366358
/// <returns>A confirmation message including the number of lines replaced, or a failure message.</returns>
367-
[Description("Replace lines in a memory file. Provide a list of edits, each with a 1-based line_number and a literal new_line (include your own trailing newline); an empty new_line deletes the line, including its line break. Fails on out-of-range or duplicate line numbers. Line numbers count lines terminated by \\n, \\r\\n, or a lone \\r; each line keeps its own terminator, and content ending in a terminator has no extra empty line after it.")]
359+
[Description("Replace lines in a memory file. Provide a list of edits, each with a 1-based line_number and a literal new_line (include your own trailing newline); an empty new_line deletes the line, including its line break. Fails on out-of-range or duplicate line numbers. Line numbers are 1-based and count lines terminated by \\n, \\r\\n, or a lone \\r; each line keeps its own terminator, and content ending in a terminator has no extra empty line after it.")]
368360
private async Task<string> ReplaceLinesAsync(string fileName, List<FileLineEdit> edits, CancellationToken cancellationToken = default)
369361
{
370362
string normalized = StorePaths.NormalizeRelativePath(fileName);
@@ -409,12 +401,6 @@ private async Task<List<FileSearchResult>> GrepAsync(string regexPattern, string
409401
string? pattern = string.IsNullOrWhiteSpace(globPattern) ? null : globPattern;
410402
IReadOnlyList<FileSearchResult> results = await this._fileStore.SearchAsync(state.WorkingFolder, regexPattern, pattern, recursive: false, cancellationToken).ConfigureAwait(false);
411403

412-
if (!this._disableSearchAlignmentCheck)
413-
{
414-
await SearchAlignment.ThrowIfMisalignedAsync(
415-
this._fileStore, state.WorkingFolder, results, regexPattern, cancellationToken, MisalignedMemoryMessage).ConfigureAwait(false);
416-
}
417-
418404
// Filter out internal files (description sidecars and memory index) so they stay hidden.
419405
var filtered = new List<FileSearchResult>(results.Count);
420406
foreach (var result in results)

‎dotnet/src/Microsoft.Agents.AI/Harness/FileMemory/FileMemoryProviderOptions.cs‎

Lines changed: 0 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -15,18 +15,4 @@ public sealed class FileMemoryProviderOptions
1515
/// that guide the agent on how to use file-based memory effectively.
1616
/// </value>
1717
public string? Instructions { get; set; }
18-
19-
/// <summary>
20-
/// Gets or sets a value indicating whether to skip the check that a store's reported
21-
/// <see cref="FileSearchMatch.LineNumber"/> values address the same lines the line editor acts on.
22-
/// </summary>
23-
/// <remarks>
24-
/// The check only runs for a store that overrides <see cref="AgentFileStore.SearchAsync"/> without
25-
/// declaring <see cref="AgentFileStore.ReportsAlignedLineNumbers"/>, and costs one extra read per
26-
/// <em>matched</em> file. Turn it off only when the store's alignment is established some other
27-
/// way: without it, a mis-numbered grep result reaches the model and an edit can land on the wrong
28-
/// line silently. Prefer setting <see cref="AgentFileStore.ReportsAlignedLineNumbers"/> on the
29-
/// store, which opts out one store rather than every store this provider is given.
30-
/// </remarks>
31-
public bool DisableSearchAlignmentCheck { get; set; }
3218
}

‎dotnet/src/Microsoft.Agents.AI/Harness/FileStore/AgentFileStore.cs‎

Lines changed: 16 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,20 @@ public abstract class AgentFileStore
9595
/// A list of search results. Each result's <see cref="FileSearchResult.FileName"/> is the matching file's
9696
/// path relative to <paramref name="directory"/>.
9797
/// </returns>
98+
/// <remarks>
99+
/// <para>
100+
/// Implementers overriding this method must report <see cref="FileSearchMatch.LineNumber"/> as a
101+
/// 1-based coordinate into <see cref="SplitLines"/> of the same content <see cref="ReadAsync"/>
102+
/// returns, and should report <see cref="FileSearchMatch.Line"/> verbatim, terminator included.
103+
/// <see cref="ScanContent"/> produces both correctly and is the recommended way to build results.
104+
/// </para>
105+
/// <para>
106+
/// Numbering against anything else — a different split rule, or content this store does not serve
107+
/// through <see cref="ReadAsync"/> — is a bug with a silent failure mode: the search looks correct,
108+
/// and the damage appears later when a line edit applies to a line the caller never saw. Cover it
109+
/// with a test that greps and then edits by the reported number.
110+
/// </para>
111+
/// </remarks>
98112
public virtual async Task<IReadOnlyList<FileSearchResult>> SearchAsync(string directory, string regexPattern, string? globPattern = null, bool recursive = false, CancellationToken cancellationToken = default)
99113
{
100114
// Compile with a match timeout to guard against catastrophic backtracking (ReDoS).
@@ -129,11 +143,7 @@ public virtual async Task<IReadOnlyList<FileSearchResult>> SearchAsync(string di
129143
}
130144
}
131145

132-
// Tagged so the file-access tools can tell the base implementation numbered these results,
133-
// without reflecting over the store's type (not trim-safe). Per call rather than per
134-
// instance: a store that defers to base.SearchAsync only sometimes must not buy permanent
135-
// trust for the results it numbers itself.
136-
return new BaseSearchResults(results);
146+
return results;
137147
}
138148

139149
/// <summary>
@@ -152,7 +162,7 @@ public virtual async Task<IReadOnlyList<FileSearchResult>> SearchAsync(string di
152162
/// The default implementation has no index to narrow with, so it walks
153163
/// <see cref="ListChildrenAsync"/> and returns every file in scope. Overriding
154164
/// <see cref="SearchAsync"/> instead is also supported, but then line numbering is the store's
155-
/// responsibility (see <see cref="SplitLines"/>) and the file-access tools verify it.
165+
/// responsibility (see <see cref="SplitLines"/>), and nothing checks it at runtime.
156166
/// </para>
157167
/// </remarks>
158168
/// <param name="directory">The relative directory being searched. Use an empty string for the root.</param>
@@ -268,26 +278,6 @@ protected virtual async Task<IReadOnlyList<string>> FindMatchingFilesAsync(strin
268278
: new FileSearchResult { FileName = fileName, Snippet = firstSnippet!, MatchingLines = matchingLines };
269279
}
270280

271-
/// <summary>
272-
/// Gets a value indicating whether this store guarantees its <see cref="FileSearchMatch.LineNumber"/>
273-
/// values are coordinates in <see cref="SplitLines"/>.
274-
/// </summary>
275-
/// <remarks>
276-
/// <para>
277-
/// Set by a store that overrides <see cref="SearchAsync"/> and numbers lines correctly — normally
278-
/// because it reports through <see cref="ScanContent"/>. Declaring it opts the store out of the
279-
/// alignment check the file-access tools otherwise run on every grep, which costs one extra read
280-
/// per <em>matched</em> file. A store that does not override <see cref="SearchAsync"/> need not
281-
/// set it: the base implementation is aligned by construction and is never checked.
282-
/// </para>
283-
/// <para>
284-
/// This is a promise, not a hint. Declaring it while numbering lines differently reinstates
285-
/// exactly the failure the check exists to catch — <c>replace_lines</c> silently editing the
286-
/// wrong line — so only set it if a test pins the alignment.
287-
/// </para>
288-
/// </remarks>
289-
public virtual bool ReportsAlignedLineNumbers => false;
290-
291281
/// <summary>
292282
/// Ensures a directory exists, creating it if necessary.
293283
/// </summary>

0 commit comments

Comments
 (0)