Return explicit found and not_found metadata tool results

Author: KSemenenko

CHANGELOG.md

@@ -5,7 +5,7 @@ All notable changes to ManagedCode.FileContext are documented here.
 ## Unreleased
 
 - Preserve UTF-8 byte accounting when a surrogate pair crosses a full-read buffer boundary.
-- Return a missing-file failure from the metadata tool so session restoration cannot turn a null result into empty content; keep the nullable direct API unchanged.
+- Return structured found/not_found metadata tool results with the logical path, preserving them through session restoration; keep the nullable direct API unchanged.
 - Verify tool-result ordering, empty/error outputs, restored-session follow-ups, and concurrent multi-file operations through real filesystem and LlmTck tests.
 - Update Meziantou.Analyzer to 3.0.203. Retain OpenAI 2.12.0 because Microsoft.Extensions.AI.OpenAI 10.9.0 requires OpenAI below 2.13.0.
 

docs/Features/file-context.md

@@ -48,15 +48,15 @@ flowchart TD
 ## Failure flows
 
 - Unsafe paths fail with `ArgumentException`; the storage provider is not called.
-- Missing files return `null` through the direct `AgentFileStore` and `IFileContext.GetInfoAsync` contracts; range reads and the `file_context_info` tool throw `FileNotFoundException`.
+- Missing files return `null` through the direct `AgentFileStore` and `IFileContext.GetInfoAsync` contracts; range reads throw `FileNotFoundException`. The `file_context_info` tool returns a structured `not_found` result with the logical path.
 - Storage failures become `IOException` values with the operation and safe logical path, preserving the provider's safe problem detail.
 - Invalid or catastrophic regex patterns fail deterministically; a regex timeout does not hang the agent invocation.
 - Oversized files, result sets, or graph exports stop at configured boundaries and report truncation or a clear limit failure.
 - Graph operations with no matching Markdown input fail clearly instead of inventing an empty knowledge base.
 
 ## Empty results and conversation history
 
-An empty file or no search matches is a valid tool outcome. With the tested Agent Framework function-invocation and OpenAI chat pipeline, these become a `role: tool` message with the matching `tool_call_id`: the content contains serialized `""` or `[]`, respectively. The metadata tool reports a missing file as a failure instead of returning `null`, because the tested Agent Framework session roundtrip converts a null function result into empty wire content. Range reads retain their structured window metadata even when their content is empty. Tool exceptions also produce a matching error result during the normal function-invocation loop.
+An empty file or no search matches is a valid tool outcome. With the tested Agent Framework function-invocation and OpenAI chat pipeline, these become a `role: tool` message with the matching `tool_call_id`: the content contains serialized `""` or `[]`, respectively. The metadata tool returns `{ "status": "not_found", "path": "missing.txt" }` for an absent file. Existing files return `{ "status": "found", "path": "notes.txt", "info": { ... } }`, where `info` contains the file metadata. Both structured results survive session restoration; a bare null function result would become empty wire content in the tested Agent Framework pipeline. Storage failures and invalid paths still fail normally. Range reads retain their structured window metadata even when their content is empty. Tool exceptions also produce a matching error result during the normal function-invocation loop.
 
 FileContext does not persist agent sessions, synthesize fallback assistant responses, or repair interrupted model/tool turns. The host owns those concerns: it must preserve call/result pairs when saving or replaying history and handle cancellation, approval pauses, and provider failures before reusing an incomplete turn. A final assistant message does not replace a tool result. Completed tool turns are also tested through Agent Framework session serialization/restoration and a subsequent user request.
 

src/ManagedCode.FileContext/FileContextInfoToolResult.cs

@@ -0,0 +1,8 @@
+using System.Text.Json.Serialization;
+
+namespace ManagedCode.FileContext;
+
+internal sealed record FileContextInfoToolResult(
+    string Status,
+    string Path,
+    [property: JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] FileContextInfo? Info);

src/ManagedCode.FileContext/FileContextToolDescriptions.cs

@@ -9,7 +9,7 @@ internal static class FileContextToolDescriptions
         "Read a bounded, one-based line range from a text file. Use this instead of a full read for large files.";
     public const string StartLine = "One-based first line to read.";
     public const string LineCount = "Number of lines to return; omitted uses the configured default.";
-    public const string GetInfo = "Return file size, media type, and last-modified time without reading its content. Fails if the file does not exist.";
+    public const string GetInfo = "Return status, path, and file metadata without reading content. Status is found with info when the file exists, or not_found when it does not.";
     public const string SearchMarkdownGraph =
         "Build a linked-data knowledge graph from scoped Markdown files and search its concepts and relationships.";
     public const string GraphQuery = "Concept or relationship query.";

src/ManagedCode.FileContext/FileContextTools.cs

@@ -15,12 +15,12 @@ public Task<FileContextRange> ReadRangeAsync(
     }
 
     [Description(FileContextToolDescriptions.GetInfo)]
-    public async Task<FileContextInfo> GetInfoAsync(
+    public async Task<FileContextInfoToolResult> GetInfoAsync(
         [Description(FileContextToolDescriptions.RelativeFilePath)] string path,
         CancellationToken cancellationToken = default)
     {
-        return await fileContext.GetInfoAsync(path, cancellationToken).ConfigureAwait(false)
-            ?? throw new FileNotFoundException($"File '{path}' was not found.", path);
+        var info = await fileContext.GetInfoAsync(path, cancellationToken).ConfigureAwait(false);
+        return new FileContextInfoToolResult(info is null ? "not_found" : "found", path, info);
     }
 
     [Description(FileContextToolDescriptions.SearchMarkdownGraph)]

tests/ManagedCode.FileContext.Tests/LlmTck/FileToolResultProtocolTests.cs

@@ -15,7 +15,7 @@ public sealed class FileToolResultProtocolTests(Xunit.Abstractions.ITestOutputHe
     [InlineData(FileAccessProvider.ReadFileToolName, "{\"fileName\":\"missing.txt\"}", "not found")]
     [InlineData(FileAccessProvider.LsToolName, "{\"directory\":\"empty\"}", "[]")]
     [InlineData(FileAccessProvider.GrepToolName, "{\"regexPattern\":\"absent\",\"directory\":\"\"}", "[]")]
-    [InlineData(FileContextToolNames.GetInfo, "{\"path\":\"missing.txt\"}", "Error: Function failed.")]
+    [InlineData(FileContextToolNames.GetInfo, "{\"path\":\"missing.txt\"}", "not_found")]
     [InlineData(FileContextToolNames.ReadRange, "{\"path\":\"empty.txt\"}", "\"content\": \"\"")]
     [InlineData(FileContextToolNames.ReadRange, "{\"path\":\"first.txt\",\"startLine\":100}", "\"content\": \"\"")]
     [InlineData(FileContextToolNames.ReadRange, "{\"path\":\"missing.txt\"}", "Error: Function failed.")]
@@ -34,6 +34,29 @@ public async Task EmptyOrFailedTool_StillSendsMatchingResult(string toolName, st
         }
     }
 
+    [Theory]
+    [InlineData("missing.txt", "not_found", false)]
+    [InlineData("first.txt", "found", true)]
+    public async Task MetadataLookup_PreservesStructuredResultAfterSessionRestore(string path, string status, bool exists)
+    {
+        var requests = await RunToolLoopAsync(LlmTckToolReplay.CreateResponse(
+            "metadata", FileContextToolNames.GetInfo, JsonSerializer.Serialize(new { path })));
+
+        foreach (var request in requests)
+        {
+            var results = LlmTckToolAssertions.AssertClosedCalls(request, "metadata");
+            using var content = JsonDocument.Parse(results[0].GetProperty("content").GetString()!);
+            content.RootElement.GetProperty("status").GetString().ShouldBe(status);
+            content.RootElement.GetProperty("path").GetString().ShouldBe(path);
+            content.RootElement.TryGetProperty("info", out var info).ShouldBe(exists);
+            if (exists)
+            {
+                info.GetProperty("path").GetString().ShouldBe(path);
+                info.GetProperty("length").GetUInt64().ShouldBe((ulong)13);
+            }
+        }
+    }
+
     [Theory]
     [InlineData(false)]
     [InlineData(true)]