Improved mailboxes to include sent mails and drafts (#1038)

app/Tests/Tools/ToolCalling/CountMailsToolTests.cs

@@ -86,6 +86,32 @@ public sealed class CountMailsToolTests : ToolRegistryTestBase
         });
     }
 
+    [Test]
+    public void AFolderGroupTellsWhetherItHoldsTheSentMailsOrTheDrafts()
+    {
+        var coverage = new MailboxCoverage(null, null, null, null, [Folder("INBOX", 120, 4), Folder("Sent Items", 40, 0, MailFolderSpecialUse.SENT), Folder("Drafts", 3, 0, MailFolderSpecialUse.DRAFTS)]);
+
+        var sent = CountMailsTool.DescribeGroup(new MailCountGroup("Sent Items", string.Empty, 40), "Sent Items", MailCountGrouping.FOLDER, coverage);
+        var drafts = CountMailsTool.DescribeGroup(new MailCountGroup("Drafts", string.Empty, 3), "Drafts", MailCountGrouping.FOLDER, coverage);
+        var inbox = CountMailsTool.DescribeGroup(new MailCountGroup("INBOX", string.Empty, 12), "INBOX", MailCountGrouping.FOLDER, coverage);
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(sent[MailToolArguments.SPECIAL_FOLDER_ARGUMENT]?.GetValue<string>(), Is.EqualTo("sent"));
+            Assert.That(sent["server_message_count"]?.GetValue<long>(), Is.EqualTo(40), "The numbers of the server stay.");
+            Assert.That(drafts[MailToolArguments.SPECIAL_FOLDER_ARGUMENT]?.GetValue<string>(), Is.EqualTo("drafts"));
+            Assert.That(inbox.ContainsKey(MailToolArguments.SPECIAL_FOLDER_ARGUMENT), Is.False);
+        });
+    }
+
+    [Test]
+    public void TheSpecialFolderIsCountedLikeTheSearchFindsIt()
+    {
+        var request = CountMailsTool.ReadRequest(Arguments("""{"special_folder":"sent","to":"alice"}"""), [WORK], TimeZoneInfo.Utc);
+
+        Assert.That(request.Conditions.SpecialFolder, Is.EqualTo(MailFolderSpecialUse.SENT));
+    }
+
     [Test]
     public void TheFunctionOffersExactlyTheMailboxesGiven()
     {
@@ -126,9 +152,9 @@ public sealed class CountMailsToolTests : ToolRegistryTestBase
     }
 
     // Stating its definition and reading its arguments needs none of the services the tool counts with:
-    private CountMailsTool Tool() => new(this.SettingsManager, new MailboxRetrievalService(this.SettingsManager, null!, null!, NullLogger<MailboxRetrievalService>.Instance), null!, NullLogger<CountMailsTool>.Instance);
+    private CountMailsTool Tool() => new(this.SettingsManager, new MailboxRetrievalService(this.SettingsManager, null!, null!, NullLogger<MailboxRetrievalService>.Instance), null!, null!, NullLogger<CountMailsTool>.Instance);
 
-    private static MailFolderRecord Folder(string path, long? messageCount, long? unseenCount) => new(path, MailFolderSpecialUse.NONE, 1, 100, null, messageCount, unseenCount, null);
+    private static MailFolderRecord Folder(string path, long? messageCount, long? unseenCount, MailFolderSpecialUse specialUse = MailFolderSpecialUse.NONE) => new(path, specialUse, 1, 100, null, messageCount, unseenCount, null);
 
     private static JsonElement Arguments(string json) => JsonSerializer.Deserialize<JsonElement>(json);
 

app/Tests/Tools/ToolCalling/MailDraftSyncTests.cs

@@ -0,0 +1,121 @@
+using AIStudio.Settings.DataModel;
+using AIStudio.Tools.Databases.IndexStore;
+using AIStudio.Tools.Mail;
+using AIStudio.Tools.Services;
+using AIStudio.Tools.ToolCallingSystem.ToolCallingImplementations.Mailboxes;
+
+using Microsoft.Extensions.Logging.Abstractions;
+
+namespace AIStudio.Tests.Tools.ToolCalling;
+
+/// <summary>
+/// Checks when a mail tool syncs a mailbox before it reads the drafts.
+/// </summary>
+/// <remarks>
+/// A user who saved a draft a moment ago and asks the AI to improve it must not hear that there is
+/// no such draft. A sync with every search would go too far, though, and a refused sign-in must never
+/// be tried again on the way, or the account of the user gets locked.
+/// </remarks>
+[TestFixture]
+[NonParallelizable]
+public sealed class MailDraftSyncTests : ToolRegistryTestBase
+{
+    private static readonly DateTimeOffset NOW = new(2026, 10, 10, 9, 0, 0, TimeSpan.Zero);
+
+    private static readonly DataSourceMailbox WORK = new() { Id = "5a1e7c3d-9b2f-4d8e-a6c4-3f0b9d2e1c75", Name = "Work" };
+
+    private static readonly IReadOnlyList<MailFolderRecord> FOLDERS = [Folder("INBOX"), Folder("Entwürfe", MailFolderSpecialUse.DRAFTS), Folder("Gesendet", MailFolderSpecialUse.SENT)];
+
+    [TestCase(true, 120, MailDraftSyncDecision.SYNC_REQUESTED)]
+    [TestCase(true, null, MailDraftSyncDecision.SYNC_REQUESTED)]
+    [TestCase(true, 30, MailDraftSyncDecision.NOT_NEEDED)]
+    [TestCase(false, 120, MailDraftSyncDecision.AUTOMATIC_REFRESH_OFF)]
+    [TestCase(false, 30, MailDraftSyncDecision.NOT_NEEDED)]
+    public void TheDraftsAreSyncedOnlyWhenTheyMayBeOutdated(bool automaticRefresh, int? secondsSinceLastSync, MailDraftSyncDecision expected)
+    {
+        var lastSync = secondsSinceLastSync is { } seconds ? NOW.AddSeconds(-seconds) : (DateTimeOffset?)null;
+
+        Assert.That(MailDraftSync.Decide(true, automaticRefresh, Coverage(lastSync, signInRefusedAtUtc: null), NOW), Is.EqualTo(expected), "A first sync which is still running gets a follow-up, since it may have looked at the drafts before the change.");
+    }
+
+    [Test]
+    public void ReceivedMailsKeepToTheInterval() =>
+        Assert.That(MailDraftSync.Decide(false, true, Coverage(NOW.AddHours(-1), signInRefusedAtUtc: null), NOW), Is.EqualTo(MailDraftSyncDecision.NOT_NEEDED));
+
+    [Test]
+    public void ARefusedSignInIsNeverTriedOnTheWay() =>
+        Assert.That(MailDraftSync.Decide(true, true, Coverage(NOW.AddHours(-1), NOW.AddMinutes(-30)), NOW), Is.EqualTo(MailDraftSyncDecision.NOT_NEEDED), "Every refused attempt brings the account of the user closer to being locked.");
+
+    [Test]
+    public void TheDraftsAreAskedForByTheSpecialFolderOrByTheirPath()
+    {
+        Assert.Multiple(() =>
+        {
+            Assert.That(AsksForDrafts(new MailConditions(new MailFilter(), null, MailFolderSpecialUse.DRAFTS), FOLDERS), Is.True);
+            Assert.That(AsksForDrafts(new MailConditions(new MailFilter(), "entwürfe", null), FOLDERS), Is.True, "A model which took the path over from a result asks for the drafts as well.");
+            Assert.That(AsksForDrafts(new MailConditions(new MailFilter(), null, MailFolderSpecialUse.SENT), FOLDERS), Is.False);
+            Assert.That(AsksForDrafts(new MailConditions(new MailFilter(), "INBOX", null), FOLDERS), Is.False);
+            Assert.That(AsksForDrafts(new MailConditions(new MailFilter { IsUnread = true }, null, null), FOLDERS), Is.False, "A search across all folders keeps to the interval.");
+        });
+    }
+
+    [Test]
+    public void AMailboxWithoutAFolderForDraftsMayGetOneWithTheNextSync() =>
+        Assert.That(AsksForDrafts(new MailConditions(new MailFilter(), null, MailFolderSpecialUse.DRAFTS), [Folder("INBOX")]), Is.True, "Some servers create the folder only when the first draft is saved.");
+
+    [Test]
+    public async Task ARequestedSyncIsQueued()
+    {
+        this.ConfigureMailbox();
+        using var service = this.CreateService();
+
+        var requested = await service.RequestMailboxSyncAsync(WORK.Id);
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(requested, Is.True);
+            Assert.That(service.GetStatuses().Single(status => status.DataSourceId == WORK.Id).State, Is.EqualTo(DataSourceEmbeddingState.QUEUED));
+        });
+    }
+
+    [Test]
+    public async Task WithoutAutomaticRefreshNoSyncIsQueued()
+    {
+        this.ConfigureMailbox();
+        this.SettingsManager.ConfigurationData.App.DataSourceIndexing.AutomaticRefresh = false;
+        using var service = this.CreateService();
+
+        var requested = await service.RequestMailboxSyncAsync(WORK.Id);
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(requested, Is.False, "Only the user starts a sync then.");
+            Assert.That(service.GetStatuses(), Is.Empty);
+        });
+    }
+
+    [Test]
+    public async Task AMailboxWhichIsNotConfiguredIsNotSynced()
+    {
+        this.ConfigureMailbox();
+        using var service = this.CreateService();
+
+        Assert.That(await service.RequestMailboxSyncAsync("0e4b8d2a-6c1f-4a9e-b3d7-5f2c8e1a9b64"), Is.False);
+    }
+
+    private static bool AsksForDrafts(MailConditions conditions, IReadOnlyList<MailFolderRecord> folders) => MailDraftSync.AsksForDrafts(conditions, conditions.ForMailbox(folders), folders);
+
+    private static MailboxCoverage Coverage(DateTimeOffset? lastCompleteSyncUtc, DateTimeOffset? signInRefusedAtUtc) => new(null, lastCompleteSyncUtc, signInRefusedAtUtc, null, FOLDERS);
+
+    private static MailFolderRecord Folder(string path, MailFolderSpecialUse specialUse = MailFolderSpecialUse.NONE) => new(path, specialUse, 1, null, null, null, null, null);
+
+    private void ConfigureMailbox()
+    {
+        this.SettingsManager.ConfigurationData.Mailboxes.Add(WORK);
+        this.SettingsManager.ConfigurationData.App.EnabledPreviewFeatures.Add(PreviewFeatures.PRE_RAG_2024);
+        this.SettingsManager.ConfigurationData.App.EnabledPreviewFeatures.Add(PreviewFeatures.PRE_MAILBOXES_2026);
+    }
+
+    // Queueing a run needs none of the services which carry it out:
+    private DataSourceEmbeddingService CreateService() => new(this.SettingsManager, null!, null!, null!, NullLogger<DataSourceEmbeddingService>.Instance);
+}

app/Tests/Tools/ToolCalling/MailToolArgumentsTests.cs

@@ -61,7 +61,7 @@ public sealed class MailToolArgumentsTests
     }
 
     [TestCase("""{}""")]
-    [TestCase("""{"from":null,"to":null,"after":null,"before":null,"is_unread":null,"is_flagged":null,"is_encrypted":null,"importance":null,"has_attachments":null,"folder":null}""")]
+    [TestCase("""{"from":null,"to":null,"after":null,"before":null,"is_unread":null,"is_flagged":null,"is_encrypted":null,"importance":null,"has_attachments":null,"folder":null,"special_folder":null}""")]
     public void ConditionsLeftOutHoldForEveryMail(string json)
     {
         var conditions = MailToolArguments.ReadConditions(Arguments(json), UserTimeZone());
@@ -70,9 +70,34 @@ public sealed class MailToolArgumentsTests
         {
             Assert.That(conditions.Filter.HasConditions, Is.False, "A strict schema makes the model pass null for every condition it does not want.");
             Assert.That(conditions.Folder, Is.Null);
+            Assert.That(conditions.SpecialFolder, Is.Null);
+            Assert.That(conditions.NamesFolder, Is.False);
         });
     }
 
+    [TestCase("sent", MailFolderSpecialUse.SENT)]
+    [TestCase("drafts", MailFolderSpecialUse.DRAFTS)]
+    public void ASpecialFolderIsReadAsWhatTheFolderIsFor(string value, MailFolderSpecialUse expected)
+    {
+        var conditions = MailToolArguments.ReadConditions(Arguments($$"""{"special_folder":"{{value}}"}"""), UserTimeZone());
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(conditions.SpecialFolder, Is.EqualTo(expected));
+            Assert.That(conditions.Folder, Is.Null);
+            Assert.That(conditions.NamesFolder, Is.True);
+            Assert.That(MailToolArguments.ToArgumentValue(expected), Is.EqualTo(value), "Results mark the mails with the value the argument takes.");
+        });
+    }
+
+    [Test]
+    public void AFolderAndASpecialFolderCannotBeCombined()
+    {
+        var message = Refusal(() => MailToolArguments.ReadConditions(Arguments("""{"folder":"Sent Items","special_folder":"sent"}"""), UserTimeZone()));
+
+        Assert.That(message, Does.Contain("'folder' and 'special_folder' cannot be combined").And.Contain("Leave out 'folder'").And.Contain("or leave out 'special_folder'"), "Two folders would match no mail at all.");
+    }
+
     [TestCase("2026-09-30", "2026-09-01")]
     [TestCase("2026-09-01", "2026-09-01")]
     public void APeriodWhichEndsBeforeItStartsIsRefused(string after, string before)
@@ -88,6 +113,8 @@ public sealed class MailToolArgumentsTests
     [TestCase("""{"after":"last week"}""", "'after' must be a date")]
     [TestCase("""{"from":""}""", "'from' must not be empty")]
     [TestCase("""{"folder":"INBOX\nArchive"}""", "'folder' must not contain control characters")]
+    [TestCase("""{"special_folder":"inbox"}""", "'special_folder' must be one of sent, drafts")]
+    [TestCase("""{"special_folder":"Sent"}""", "'special_folder' must be one of sent, drafts")]
     public void AConditionWhichCannotBeMeantAsWrittenIsRefused(string json, string expectedMessage)
     {
         var message = Refusal(() => MailToolArguments.ReadConditions(Arguments(json), UserTimeZone()));
@@ -121,8 +148,8 @@ public sealed class MailToolArgumentsTests
     {
         var folders = new[] { Folder("INBOX"), Folder("INBOX/Projects"), Folder("Archive"), Folder("archive") };
 
-        var inbox = new MailConditions(new MailFilter(), "Inbox").ForMailbox(folders);
-        var archive = new MailConditions(new MailFilter(), "ARCHIVE").ForMailbox(folders);
+        var inbox = new MailConditions(new MailFilter(), "Inbox", null).ForMailbox(folders);
+        var archive = new MailConditions(new MailFilter(), "ARCHIVE", null).ForMailbox(folders);
 
         Assert.Multiple(() =>
         {
@@ -134,7 +161,7 @@ public sealed class MailToolArgumentsTests
     [Test]
     public void AFolderTheMailboxDoesNotHaveMatchesNoMail()
     {
-        var filter = new MailConditions(new MailFilter { IsUnread = true }, "Projects").ForMailbox([Folder("INBOX")]);
+        var filter = new MailConditions(new MailFilter { IsUnread = true }, "Projects", null).ForMailbox([Folder("INBOX")]);
 
         Assert.Multiple(() =>
         {
@@ -143,10 +170,33 @@ public sealed class MailToolArgumentsTests
         });
     }
 
+    [Test]
+    public void ASpecialFolderIsFoundByWhatTheServerMarksItAsWhateverItsName()
+    {
+        var folders = new[] { Folder("INBOX"), Folder("Gesendete Elemente", MailFolderSpecialUse.SENT), Folder("Sent"), Folder("Entwürfe", MailFolderSpecialUse.DRAFTS) };
+
+        var sent = new MailConditions(new MailFilter(), null, MailFolderSpecialUse.SENT).ForMailbox(folders);
+        var drafts = new MailConditions(new MailFilter(), null, MailFolderSpecialUse.DRAFTS).ForMailbox(folders);
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(sent.FolderPaths, Is.EqualTo(new[] { "Gesendete Elemente" }), "A folder merely named like the sent mails is not theirs.");
+            Assert.That(drafts.FolderPaths, Is.EqualTo(new[] { "Entwürfe" }));
+        });
+    }
+
+    [Test]
+    public void ASpecialFolderTheMailboxDoesNotHaveMatchesNoMail()
+    {
+        var filter = new MailConditions(new MailFilter(), null, MailFolderSpecialUse.DRAFTS).ForMailbox([Folder("INBOX"), Folder("Drafts")]);
+
+        Assert.That(filter.FolderPaths, Is.Empty, "A mailbox which left out its drafts, or whose server does not mark them, must not get the whole mailbox back.");
+    }
+
     [Test]
     public void WithoutAFolderEveryFolderCounts()
     {
-        Assert.That(new MailConditions(new MailFilter(), null).ForMailbox([Folder("INBOX")]).FolderPaths, Is.Null);
+        Assert.That(new MailConditions(new MailFilter(), null, null).ForMailbox([Folder("INBOX")]).FolderPaths, Is.Null);
     }
 
     [Test]
@@ -161,14 +211,15 @@ public sealed class MailToolArgumentsTests
             {
                 MailToolArguments.MAILBOX_IDS_ARGUMENT, MailToolArguments.FROM_ARGUMENT, MailToolArguments.TO_ARGUMENT, MailToolArguments.AFTER_ARGUMENT, MailToolArguments.BEFORE_ARGUMENT,
                 MailToolArguments.IS_UNREAD_ARGUMENT, MailToolArguments.IS_FLAGGED_ARGUMENT, MailToolArguments.IS_ENCRYPTED_ARGUMENT, MailToolArguments.IMPORTANCE_ARGUMENT,
-                MailToolArguments.HAS_ATTACHMENTS_ARGUMENT, MailToolArguments.FOLDER_ARGUMENT,
+                MailToolArguments.HAS_ATTACHMENTS_ARGUMENT, MailToolArguments.FOLDER_ARGUMENT, MailToolArguments.SPECIAL_FOLDER_ARGUMENT,
             }));
+            Assert.That(properties[MailToolArguments.SPECIAL_FOLDER_ARGUMENT]!["enum"]!.AsArray().Select(value => value?.GetValue<string>()), Is.EqualTo(new[] { "sent", "drafts" }));
             Assert.That(properties[MailToolArguments.MAILBOX_IDS_ARGUMENT]!["items"]!["enum"]!.AsArray().Select(id => id!.GetValue<string>()), Is.EqualTo(new[] { WORK.Id, PRIVATE.Id }));
             Assert.That(schema["required"]!.AsArray(), Is.Empty, "Every condition may be left out.");
         });
     }
 
-    private static MailFolderRecord Folder(string path) => new(path, MailFolderSpecialUse.NONE, 1, null, null, null, null, null);
+    private static MailFolderRecord Folder(string path, MailFolderSpecialUse specialUse = MailFolderSpecialUse.NONE) => new(path, specialUse, 1, null, null, null, null, null);
 
     private static JsonElement Arguments(string json) => JsonSerializer.Deserialize<JsonElement>(json);
 

app/Tests/Tools/ToolCalling/SearchMailsToolTests.cs

@@ -230,7 +230,7 @@ public sealed class SearchMailsToolTests : ToolRegistryTestBase
         {
             ReceivedSinceUtc = new DateTimeOffset(2026, 8, 31, 22, 0, 0, TimeSpan.Zero),
             Importance = MailImportance.HIGH,
-        }, "INBOX");
+        }, "INBOX", null);
 
         var description = MailToolResults.DescribeConditions(conditions, timeZone);
 
@@ -243,6 +243,55 @@ public sealed class SearchMailsToolTests : ToolRegistryTestBase
         });
     }
 
+    [Test]
+    public void TheConditionsShowTheSpecialFolderAsTheArgumentTakesIt()
+    {
+        var description = MailToolResults.DescribeConditions(new MailConditions(new MailFilter(), null, MailFolderSpecialUse.DRAFTS), TimeZoneInfo.Utc);
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(description[MailToolArguments.SPECIAL_FOLDER_ARGUMENT]!.GetValue<string>(), Is.EqualTo("drafts"));
+            Assert.That(description.ContainsKey(MailToolArguments.FOLDER_ARGUMENT), Is.False);
+        });
+    }
+
+    [TestCase(new[] { "INBOX" }, null)]
+    [TestCase(new[] { "Sent Items" }, "sent")]
+    [TestCase(new[] { "Drafts" }, "drafts")]
+    [TestCase(new[] { "Drafts", "Sent Items" }, "sent")]
+    [TestCase(new[] { "Elsewhere" }, null)]
+    public void AMailAmongTheSentMailsOrTheDraftsIsMarked(string[] folderPaths, string? expected)
+    {
+        IReadOnlyList<MailFolderRecord> folders = [Folder("INBOX"), Folder("Sent Items", MailFolderSpecialUse.SENT), Folder("Drafts", MailFolderSpecialUse.DRAFTS)];
+
+        Assert.That(MailToolResults.GetSpecialFolder(folderPaths, folders), Is.EqualTo(expected), "A mail in the folder of the sent mails was sent, even when a copy lies among the drafts. A folder the index does not know marks nothing.");
+    }
+
+    [Test]
+    public void AMissingSpecialFolderListsTheFoldersToPickFrom()
+    {
+        var description = new JsonObject();
+        var issues = new JsonArray();
+
+        MailToolResults.DescribeMissingFolder(description, issues, MailFolderSpecialUse.SENT, ["INBOX", "Gesendet"], 2);
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(issues.Single()!.GetValue<string>(), Does.Contain("no folder for sent mails").And.Contain("either because the user left it out or because the server does not mark it").And.Contain("pass its path in 'folder' instead of 'special_folder'"));
+            Assert.That(description["folders"]!.AsArray().Select(folder => folder!.GetValue<string>()), Is.EqualTo(new[] { "INBOX", "Gesendet" }));
+        });
+    }
+
+    [Test]
+    public void AMissingFolderByPathOffersNoOtherArgument()
+    {
+        var issues = new JsonArray();
+
+        MailToolResults.DescribeMissingFolder(new JsonObject(), issues, null, ["INBOX", "Archive"], 120);
+
+        Assert.That(issues.Single()!.GetValue<string>(), Does.Contain("no folder with the path given in 'folder'").And.Contain("The first 2 of its 120 folders").And.Not.Contain("special_folder"));
+    }
+
     [Test]
     public void SemanticSearchNeverSeesAMailbox()
     {
@@ -250,7 +299,9 @@ public sealed class SearchMailsToolTests : ToolRegistryTestBase
     }
 
     // Stating its definition and reading its arguments needs none of the services the tool searches with:
-    private SearchMailsTool Tool() => new(this.SettingsManager, new MailboxRetrievalService(this.SettingsManager, null!, null!, NullLogger<MailboxRetrievalService>.Instance), null!, NullLogger<SearchMailsTool>.Instance);
+    private SearchMailsTool Tool() => new(this.SettingsManager, new MailboxRetrievalService(this.SettingsManager, null!, null!, NullLogger<MailboxRetrievalService>.Instance), null!, null!, NullLogger<SearchMailsTool>.Instance);
+
+    private static MailFolderRecord Folder(string path, MailFolderSpecialUse specialUse = MailFolderSpecialUse.NONE) => new(path, specialUse, 1, null, null, null, null, null);
 
     private static JsonElement Arguments(string json) => JsonSerializer.Deserialize<JsonElement>(json);